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Jersey-2.x-User-Guide 


T 


Chinese translation of Jersey 2.x User Guide.There is also a GitBook version of the book: 
http://www.gitbook.com/book/waylau/jersey-2-user-guide. Let's RESD! 


(Jersey 2.x 用 户 指南 》 ， 中 文 翻译 。 最 近 在 做 Java RESTful 相关 的 项 目 ， 借 此 机 会 学 习 了 
一 把 Jersey， 发 现 网 上 中 文 的 资料 比较 少 ， 而 且 Jersey 的 更 新 比较 快 ， 很 多 博文 都 老 了 。 之 前 
5 it JLA € T Jersey demo > 4, T AE A &Fhitps://waylau.com/categories/#Jersey ° 3ft Jj 
也 在 做 REST 方面 的 总 结 ， 可 以 参阅 《REST 实战 》。 


文本 用 到 的 所 有 例子 源码 可 以 在 https://github.com/waylau/Jersey-2.x-User-Guide-Demos 获 
取 到 。 


REME (2018-4-17) Jersey 的 最 新 版 本 为 2.27， 利 用 业余 时 间 对 此 进行 翻译 ， 并 在 原文 的 
基础 上 ， 插 入 配 图 ， 图 文 并 诚 方 便 用 户 理解 。 如 有 勘误 欢迎 指正 ， 点 此 。 如 有 兴趣 ， 也 可 以 
参与 到 本 翻译 工作 中 来 :) 另外 有 GitBook 的 版 本 方便 阅读 
http://www.gitbook.com/book/waylau/jersey-2-user-guide 


从 目录 开始 阅读 吧 ! 


Contact: 


e Blog:waylau.com 


Gmail: waylau521@gmail.com 
e Weibo: waylau521 


Twitter: waylau521 


Github : waylau 


Preface 8| 3 
ix € Jersey 2.x 的 用 户 指南 。 我 们 极力 将 它 能 与 我 们 新 增 的 功能 保持 一 致 。 当 阅读 本 指南 ， 作 
为 补充 ， 也 请 移 步 至 Jersey API documentation 查看 Jersey 的 特性 和 API ° 


欢迎 任何 对 本 指南 的 建议 和 提问 ， 可 以 联系 Users@jersey.java.net, 同 样 的 ， 发 现 勘 误 ， 也 可 
以 在 Jersey JIRA lssue Tracker 提问 。 

EAE : 如 发 现 中 文 翻译 勘误 欢迎 指正 ， 点 此 。 本 文 所 有 例子 的 源码 ， 可 以 

在 https://github.com/waylau/Jersey-2.x-User-Guide-Demos 获取 到 。 


Chapter 1. Getting Started 开始 


本 章 提供 了 一 个 如 何 开始 使 用 Jersey 构 建 RESTful 服 务 的 快速 介绍 。 这 里 描述 的 示例 使 用 轻 量 
级 的 Grizzly HTTP 服 务 器 。 在 本 章 的 最 后 你 将 看 到 如 何 实现 相同 的 功能 的 JavaEE 的 Web 应 用 
程序 ， 该 程序 可 以 部 署 在 任何 支持 Servlet 2.5 和 更 高 版 本 的 servlet 容器 里 面 。 


译 者 注 : 本 章 所 有 例子 的 源码 ， 可 以 在 https://github.com/waylau/Jersey-2.x-User-Guide- 
Demos 获取 到 。 


1.1. Creating a New Project from Maven 
Archetype 从 Maven Archetype 创 建 一 个 新 项 
El 


创建 Jersey 工程 需要 使 用 Apache 的 Maven 软 件 工 程 和 管理 工具 。 所 有 的 Jersey 产 品 模块 都 
可 以 在 Maven 中 央 库 中 找到 。 因 此 基于 Maven 的 模块 都 是 现成 的 ， 不 需要 在 Maven 中 增加 
其 他 的 Jersey 模块 。( 译 者 注 : 有 关 Maven 的 安装 、 使 用 ， 可 以 参考 Apache Maven 3.1.0 安 
装 、 部 署 、 使 用 ) 


注意 : 如 果 你 想 要 使 用 最 新 的 Jersey 模块 的 SNAPSHOT 版 本 ( 译 者 注 : SNAPSHOT 版 本 
代表 不 稳定 、 尚 处 于 开发 中 的 版 本 ) ， 需 要 在 pom.xml 中 添加 如 下 内 容 : 


<repository> 
<id>snapshot -repository.java.net</id> 
<name>Java.net Snapshot Repository for Maven</name> 
<url>https://maven. java.net/content/repositories/snapshots/</url> 
<layout>default</layout> 

</repository> 


使 用 Maven 的 工程 创建 一 个 Jersey 项 目 是 最 方便 的 ， 让 我 们 用 这 种 方法 来 看 一 下 它 是 怎么 实 
现 的 。 让 我 们 创建 一 个 新 的 Jersey 项 目 ,运行 在 Grizzly 容 器 。 我 们 使 用 Jersey-provided 的 
maven archetype。 创 建 一 个 项 目 ， 需 要 执行 下 面 的 代码 : 


mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2 \ 
-DarchetypeGroupId-org.glassfish.jersey.archetypes -DinteractiveMode-false \ 
-DgroupId-com.example -DartifactId=simple-service -Dpackage-com.example \ 


-DarchetypeVersion-2.16 


Em BIER: C\Windows\system32\cmd.exe 





4 KB at 2.9 KB/sec? 


larchetypes/jersey-quickstart-grizzly2/2.12/jersey-quickstart-grizz1y2-2.12.pom (E 


[INFO] Using following parameters for creating project from Old (1.x> Archetype: 


jersey—quickstart—grizzly2:2.12 


Parameter: groupId, Value: com.example 

Parameter: packageName, Value: com.example 

Parameter: package. Value: com.example 

Parameter: artifactId. Value: simple-service 

Parameter: basedir. Value: D:\workspaceGithubWersey-2.x—User—Guide—Demos 


[INFO] Parameter: version, Value: 1.@6-SNAPSHOT 
[INFO] project created from Old (1.x) Archetype in dir: D:\workspaceGithubWerselg 
iy-2 .x-UÜser-Guide-Demos \demo-1.1\simple-service 


[INFO] Total time: 18.446 s 
[INFO] Finished at: 2014-88-38TU89:11:2'7-408 
[INFO] Final Memory: 16M/25M 





:ag 


D: Works paceGit hub\WJersey-2 .x-User—Guide—Demos \demo-1 .1> - 





« Jersey-2x-User-Guide-Demos » demo-1.1 > v | +4 || HE demo-1.1 
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在 你 的 项 目 里 面 随意 调整 pom.xml 内 的 groupld 
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， 包 名 和 版 本 号 就 可 以 成 为 一 个 新 的 项 目 。 


1.2. Exploring the Newly Created Project 探 
索 新 项 目 


如 果 用 Jersey maven archetype 成 功 创建 了 这 个 项 目 ， 那 么 在 你 当前 的 路 径 下 就 已 经 创建 了 
一 个 名 为 simple-service 项 目 。 它 包含 了 一 个 标准 的 Maven 项 目 结构 : 


e 标准 的 管理 配置 文件 pom.xml 
e 原文 路 径 src/main/java/ 
e. 测试 文件 路 径 src/test/java/ 


在 原文 路 径 下 的 com.example 包 中 有 两 个 class 文件 ， 这 个 Main 类 主要 是 负责 承接 Grizzly 
容器 ， 同 时 也 为 这 个 容器 配置 和 部 署 JAX-RS 应 用 。 在 同一 个 包 内 的 另外 一 个 类 
MyResource 类 是 JAX-RS 的 一 个 实现 的 源 代 码 ， 如 下 : 


package com.example; 


import javax.ws.rs.GET; 

import javax.ws.rs.Path; 

import javax.ws.rs.Produces; 
import javax.ws.rs.core.MediaType; 


* Donot rac VE ES EA ACAN at 村 
Root resource (exposed at "myresource" path) 


QPath("myresource") 
public class MyResource { 





* Method handling HTTP GET The ret d objec ll be sei 
to the client as "text/plain" media type. 
* @return String that will be returned as a text/plain response. 


@GET 
@Produces(MediaType. TEXT_PLAIN) 
public String getIt() { 

return <Got TERS 


一 个 JAX-RS 资源 是 一 个 可 以 处 理 绑 定 了 资源 的 URI 的 HTTP 请 求 的 带 有 注解 的 POJO， 详 细 

内 容 可 以 看 第 三 章 。 在 我 们 的 例子 中 ， 单 一 的 资源 暴露 了 一 个 公开 的 方法 ， 能 够 处 理 HTTP 

SETS R> MEE /myresource URI 路 径 下 ， 可 以 产生 媒体 类 型 为 “text/plain” 的 响应 消息 。 在 
个 示例 中 ， 资 源 返 回 相 同 的 "Got it" 应 对 所 有 客户 端的 要 求 。 


在 src/test/java 目录 下 的 MyResourceTest 类 是 对 MyResource 的 单元 测试 ， 他 们 具有 相同 
的 包 com.example 


package com.example; 
import javax.ws.rs.client.Client; 
import javax.ws.rs.client.ClientBuilder; 


import javax.ws.rs.client.WebTarget; 


import org.glassfish.grizzly.http.server.HttpServer; 


public class MyResourceTest { 


private HttpServer server; 
private WebTarget target; 


QBefore 
public void setUp() throws Exception { 
server - Main.startServer(); 


Client c - ClientBuilder.newClient(); 
target - c.target(Main.BASE URI); 


QAfter 
public void tearDown() throws Exception { 
server.stop(); 


/** 
* Test to see that the message "Got it!" is sent in the response. 
27 
@Test 
public void testGetIt() { 
String responseMsg = target.path("myresource").request().get(String.class); 
assertEquals("Got it!", responseMsg); 


在 这 个 单元 测试 中 (EAE : 测试 用 到 了 JUnit) > #AAK main.startServer() 首先 将 
Grizzly 容器 启动 ， 而 后 服务 器 应 用 部 署 到 测试 中 的 setup() 方法 。 接 下 来 ， 一 个 JAX-RS € 
户 端 组 件 在 相同 的 测试 方法 创建 。 先是 一 个 新 的 JAX-RS 客 户 端 实例 生成 并 ， 接 着 JAX-RS 
web target 部 件 指向 我 们 部 署 的 应 用 程序 上 下 文 的 根 : http://localhost:8080/myapp/ ( 
Main.BASE_URI 的 常量 值 ) 存储 在 单元 测试 类 目标 区 。 这 个 区 被 用 于 实际 的 单元 测试 方法 


( testgetit() ) 9 


在 testgetit() 方 法 中 ，JAX-RS X P 3 API 是 用 来 连接 并 发 送 HTTP GET 请 求 的 MyResource 
JAX-RS 资源 类 侦 听 在 /myresource 的 URI。 同 样 作为 JAX-RS API 方法 调用 链 的 一 部 分 ， 回 
应 以 Java 字 符 囊 类 型 被 读 到 。 在 测试 方法 的 第 二 行 ， 响 应 的 内 容 (从 服务 器 返回 的 字符 囊 ) 
跟 测 试 断言 预期 短语 比较 (EDU: BP assertEquals J) 。 要 了 解 更 多 有 关 使 用 JAX-RS 
客户 端 AP1， 请 参阅 第 5 章 客 户 端 AP|。 


1.3. Running the Project 运行 项 目 


项 目 有 了 ， 进 入 项 目的 跟 目 录 (BP \simple-service ) 现在 先 测试 运行 


$ mvn clean test 


项 目 将 会 被 编译 ， 并 且 进 行 单元 测试 


Running com.example.MyResourceTest 

^H 30, 2014 9:35:06 E+ org.glassfish.grizzly.http.server.NetworkListener sta 
rt 

INFO: Started listener bound to [localhost:8080] 

^H 30, 2014 9:35:06 上 午 org.glassfish.grizzly.http.server.HttpServer start 
INFO: [HttpServer] Started. 

^H 30, 2014 9:35:07 上 午 org.glassfish.grizzly.http.server.NetworkListener shu 
tdownNow 

INFO: Stopped listener bound to [localhost:8080] 

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.485 sec 


Results : 
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 


ENE OMNES 
[INFO] BUILD SUCCESS 

DINO) S E 
[INFO] Total time: 02:21 min 

[INFO] Finished at: 2014-08-30T09:35:07+08:00 

[INFO] Final Memory: 13M/31M 
LINEO 


上 面 可 以 看 看 到 测试 通过 ， 下 面 我 们 用 标准 模式 运行 


ENN 


$ mvn exec:java 


运行 结果 如 下 : 


[INFO] Scanning for projects... 

[INFO] 

[INFO] Using the builder org.apache.maven.lifecycle.internal.builder.singlethrea 
ded.SingleThreadedBuilder with a thread count of 1 

[INFO] 

(NEO) eesesesssccsesssessesbsenenesssobbonaesasenbeosceusonbEBOneasbesecegs enr 
[INFO] Building simple-service 1.0-SNAPSHOT 

[EINE ON 
[INFO] 

[INFO] >>> exec-maven-plugin:1.2.1:java (default-cli) @ simple-service >>> 
[INFO] 

[INFO] <<< exec-maven-plugin:1.2.1:java (default-cli) @ simple-service <<< 
[INFO] 

[INFO] --- exec-maven-plugin:1.2.1:java (default-cli) @ simple-service --- 

^H 30, 2014 9:36:57 E+ org.glassfish.grizzly.http.server.NetworkListener sta 
rt 

INFO: Started listener bound to [localhost:8080] 

^H 30, 2014 9:36:57 EF org.glassfish.grizzly.http.server.HttpServer start 
INFO: [HttpServer] Started. 

Jersey app started with WADL available at http://localhost:8080/myapp/applicatio 
n.wadl 

Hit enter to stop it... 


项 目 已 经 运行 ， 项 目的 WADL 描述 存在 于 http://1ocalhost:8080/myapp/application.wadl 

URI 中 ,将 该 URI 在 控制 台 以 curl 命令 执行 或 者 浏览 器 中 运行 ， 就 能 看 到 该 WADL 描述 以 
XML 格式 展示 。 

€ ca O localhost:8080/myapp/application.wadl x 三 


This XML file does not appear to have any style information associated with it. The 
document tree is shown below. 


v application xmlns="http://wadl. dev. java. net/2009/02" > 
<doc xmlns:jersey-"http:// jersey. java.net/" jersey:generatedBy-" Jersey: 2.12 2014-08-25 
11:15:46" /» 
<doc xmlns:jersey-"http:// jersey. java.net/" jersey:hint-" This is simplified WADL with user 
and core resources only. To get full WADL with extended resources use the query parameter 
detail. Link: http://localhost :8080/myapp/ application. wadl?det ail=true” /> 
<grammars/ > 
¥<resources base="http://localhost : 8080/myapp/* > 
v<resource path="myresource’ > 
v£method id-"getIt" name="GET"> 
v <response> 
<representation medialType="text/plain’ /> 
</response> 
</method> 
</resource> 
</resources> 
</application> 


更 多 WADL 的 内 容 ， 请 查考 


Chapter 16, WADL Support 





ie http://localhost:8080/myapp/myresource P~ i 





Got it! 


= 


接 下 来 试 下 与 部 署 在 /myresource 下 面 的 资源 的 交互 2 将 资 源 的 URL 输 入 浏 览 器 * 或 者 在 控 
制 台 用 curi 命令 执行 ( 译 者 注 : 如 果 没 有 安装 curl, 请 参考 curl 安 装 ) : 


$ curl http://localhost :8080/myapp/myresource 
Got it! 


E SLES: CA\Windows\system32\cmd.exe || =) mm] 
Microsoft Windows Chi 6.1.76611 ^ 


有 <c>) 2609 Microsoft Corporation。 E 


:Wsers Vidministrator»curl http://localhost :-8686/myapp/myresource 
ot it? 
= Wsers \Administrator>, 





用 -i 命令 获取 所 有 回应 的 头 文件 信息 : 


$ curl -i http://localhost :8080/myapp/myresource 
HTTP/1.1 200 OK 

Content-Type: text/plain 

Date: Sat, 30 Aug 2014 02:23:25 GMT 


Content-Length: 7 


Got it! 


注意 到 Content-Type: text/plain 是 在 MyResource 类 中 用 @Produces 注解 的 。 


如 果 想 看 到 更 回信 息 ， 可 以 变换 不 同 的 curl 命令 参数 。 举 例 : 


$ curl -v http://localhost :8080/myapp/myresource 


* Adding handle: conn: 0x5bc180 

* Adding handle: send: 0 

* Adding handle: recv: 0 

* Curl_addHandleToPipeline: length: 1 

* - Conn © (0x5bc180) send_pipe: 1, recv_pipe: 0 
* About to connect() to localhost port 8080 (#0) 
td Trying 127.0.0.1... 

* Connected to localhost (127.0.0.1) port 8080 (#0) 
GET /myapp/myresource HTTP/1.1 

User-Agent: curl/7.33.0 

Host: localhost :8080 

Accept: */* 


HTTP/1.1 200 OK 

Content-Type: text/plain 

Date: Sat, 30 Aug 2014 01:55:06 GMT 
Content-Length: 7 


N A A AN A VV VV N 


Got it!* Connection #0 to host localhost left intact 


fi HE 


e 目录 
e 上 一 节 1.2 探 索 新 项 目 
e 下 一 节 14 创建 一 个 JavaEE 的 Web 项 目 


1.4. Creating a JavaEE Web Application £| 
建 一 个 JavaEE 的 Web 项 目 


与 1.1 类 似 的 创建 项 目的 流程 ， 创 建 JavaEE Web 项 目 仅 需 要 打包 成 WAR 并 且 部 署 到 
Servlet 容器 。 除 了 基于 Grizzly 的 archetype, Jersey 也 提供 了 Maven archetype 用 来 创建 
web 项 目 ， 命 令 如 下 : 


mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-webapp \ 

-DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode-f 
alse \ 

-DgroupId=com.example -DartifactId=simple-service-webapp -Dpackage=com 
.example \ 

-DarchetypeVersion=2.16 


在 你 的 项 目 里 面 随意 调整 pom.xml 内 的 groupld， 包 号 和 版 本 号 就 可 以 成 为 一 个 新 的 项 目 。 


此 时 ， simple-service-webapp 已 经 创建 ， 符 合 Maven 的 项 目 结构 : 


e 标准 的 管理 配置 文件 pom.xml 
原文 件 路 径 src/main/java 
资源 文件 路 径 src/main/resources 


web 应 用 文件 src/main/webapp 





el « simple-service-webapp » src » main > 
| 


SEE) BSM) 工具 中” 帮助 (H) 
包含 到 库 中 v 共享 新 建文 件 去 


Ea z a 

m . |) Java 

近 访 问 的 位 置 |) resources 
L webapp 


该 项 目 包含 相同 的 MyResouce JAX-RS 资 源 类 。 它 不 包含 任何 单元 测试 以 及 它 不 包含 一 个 主 
类 ， 这 在 以 前 是 用 在 Grizzly 容器 的 项 目 设 置 。 相 反 ， 在 src/main/webapp/WEB-INF F > È 
包含 了 标准 的 JavaEE Web 应 用 的 web.xml 部 署 描述 符 。 项 目 中 的 最 后 一 个 组 件 是 一 个 
index.jsp 页 面 作为 这 次 MyResource 资源 类 打包 和 部 署 的 应 用 程序 客户 端 。 


项 目 打 包 成 WAR ,执行 : 


mvn clean package 


打包 成 功 ， 如 下 : 


[INFO] 

[INFO] --- maven-war-plugin:2.2:war (default-war) @ simple-service-webapp --- 
[INFO] Packaging webapp 

[INFO] Assembling webapp [simple-service-webapp] in [D:\workspaceGithub\Jersey-2 
.x-User -Guide-Demos\demo-1.4\simple-service-webapp\target\simple-service-webapp ] 


[INFO] Processing war project 

[INFO] Copying webapp resources [D:\workspaceGithub\Jersey-2.x-User-Guide-Demos\ 
demo-1.4Nsimple-service-webappNsrcNnainNwebapp] 

[INFO] Webapp assembled in [176 msecs] 

[INFO] Building war: D:\workspaceGithub\Jersey-2.x-User-Guide-Demos\demo-1.4\sim 
ple-service-webappNtargetNsimple-service-webapp.war 

[INFO] WEB-INFNweb.xml already added, skipping 

ENEON 
[INFO] BUILD SUCCESS 

ENEON ascesnecoonosmacesansacsenmaace 
[INFO] Total time: 02:29 min 

[INFO] Finished at: 2014-08-30T10:05:56+08:00 

[INFO] Final Memory: 12M/29M 

NRO] ssessosscomscosnossesasnesdquaceas cscs canseqnecmescoascsadacassscaaace 


打包 的 WAR (位 于 ./target/simple-service-webapp.war ) 可 以 将 它 部 署 到 您 任意 的 Servlet 
« simple-service-webapp » target > -»:1*4|| Ex 


E) V IAM 帮助 (H) 
引 含 到 库 中 ”共享 ”新 建文 件 夫 


*kspaceDW 5 ZFR 
^k FB47 

SS (s classes 
"kspaceGit 


|» generated-sources 


kspaceGithub |) maven-archiver 
ngulaJS-demos |. simple-service-webapp 
radle-2-User-Guide | | simple-service-webapp.war 


irsey-2x-User-Guide 


1.4 创建 一 个 JavaEE 的 Web 项 目 


& http://localhost:8089/simple-service-webapp/webapi/myresource 


| [S] localhost 





注意 : BH Jersey RA > Servlet 容器 版 本 应 该 是 不 低 于 2.5， 如 果 想 支持 更 高 的 特性 (比如 
JAX-RS 2.0 Async Support) ，Servlet 容 器 版 本 应 该 是 不 低 于 3.0 
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1.5. Creating a Web Application that can 
be deployed on Heroku 创建 能 部 署 在 
Heroku 上 面 的 Web 项 目 


与 1.4 节 类 似 的 ， 创 建 一 个 Web 项 目 打 包 成 WAR 部 署 在 Servlet 容器 或 者 发 布 到 Heroku。 执 
8 


mvn archetype:generate -DarchetypeArtifactId-jersey-heroku-webapp \ 

-DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode-f 
alse \ 

-DgroupId=com.example -DartifactId=simple-heroku-webapp -Dpackage=com. 
example \ 

-DarchetypeVersion=2.16 


在 你 的 项 目 里 面 随意 调整 pom.xml 内 的 groupld， 包 号 和 版 本 号 就 可 以 成 为 一 个 新 的 项 目 。 
此 时 ， simple-heroku-webapp 已 经 创建 ， 符 合 Maven 的 项 目 结构 : 


e 标准 的 管理 配置 文件 : pom.xml 

e 原文 件 路 径 : src/main/java 

e 资源 文件 路 径 : src/main/resources 

e Web 应 用 文件 : src/main/webapp 

e 原文 件 测 试 (基于 JerseyTest) : src/test/java 

e Heroku 系 统 属性 Mp : system.properties 
e Heroku 应 用 的 进程 类 型 列表 : Procfile 


该 项 目 包含 一 个 JAX-RS 资 源 类 MyResouce， 和 一 个 资源 的 方法 会 返回 的 简单 文本 。 确 保 资 
源 的 正确 测试 ，MyResourceTest 是 一 个 端 到 端的 测试 案例 〈 测 试 是 基于 JerseyTest, 详 见 
Chapter 24, Jersey Test Framework) ° X44 simple-service-webapp 项 目 ， 在 
src/main/webapp/WEB-INF 下 ， 它 包含 了 标准 的 JavaEE Web 应 用 的 web.xml 部 署 描述 符 ， 
目标 是 部 署 在 一 个 Servlet 容器 (本 例 将 运行 在 Heroku 的 Jetty 容器 ) ° 


项 目 打包 成 WAR, 执 行 


mvn clean package 


包 成 功 ， 如 下 


Results : 


Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 


[INFO] 

[INFO] --- maven-war-plugin:2.2:war (default-war) @ simple-heroku-webapp --- 
[INFO] Packaging webapp 

[INFO] Assembling webapp [simple-heroku-webapp] in [D:\workspaceGithub\Jersey-2. 
x-User -Guide-Demos\demo-1.5\simple-heroku-webapp\target\simple-heroku-webapp ] 
[INFO] Processing war project 

[INFO] Copying webapp resources [D:NworkspaceGithubNJersey-2.x-User-Guide-DemosN 
demo-1.5Nsimple-heroku-webappNsrcNmainNwebapp] 

[INFO] Webapp assembled in [103 msecs] 

[INFO] Building war: D:\workspaceGithub\Jersey-2.x-User-Guide-Demos\demo-1.5\sim 
ple-heroku-webapp\target\simple-heroku-webapp.war 

[INFO] WEB-INF\web.xml already added, skipping 

[INFO] 

[INFO] --- maven-dependency-plugin:2.8:copy-dependencies (copy-dependencies) @ s 
imple-heroku-webapp --- 

[INFO] Copying jersey-container-servlet-core-2.12.jar to D:\workspaceGithub\Jers 
ey-2.x-User-Guide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjersey-c 
ontainer-servlet-core-2.12.jar 

[INFO] Copying hk2-api-2.3.0-b10.jar to D:NworkspaceGithubNJersey-2.x-User-Guide 
-Demos\demo-1.5\simple-heroku-webapp\target \dependency\hk2-api-2.3.0-b10. jar 
[INFO] Copying javassist-3.18.1-GA.jar to D:\workspaceGithub\Jersey-2.x-User-Gui 
de-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjavassist-3.18.1-GA.jar 


[INFO] Copying jetty-security-9.0.6.v20130930.jar to D:NworkspaceGithubNJersey-2 
.X-User -Guide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjetty-securi 
ty-9.0.6.v20130930.jar 

[INFO] Copying validation-api-1.1.0.Final.jar to D:\workspaceGithub\Jersey-2.x-U 
ser-Guide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNvalidation-api-1 
.1.0.Final.jar 

[INFO] Copying jetty-webapp-9.0.6.v20130930.jar to D:\workspaceGithub\Jersey-2.x 
-User-Guide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjetty-webapp-9 
.0.6.v20130930. jar 

[INFO] Copying jersey-client-2.12.jar to D:NworkspaceGithubNJersey-2.x-User-Guid 
e-Demos\demo-1.5\simple-heroku-webapp\target\dependency\jersey-client-2.12.jar 
[INFO] Copying osgi-resource-locator-1.0.1.jar to D:\workspaceGithub\Jersey-2.x- 
User -Guide-Demos\demo-1.5\simple-heroku-webapp\target\dependency\osgi-resource-1 
ocator-1.0.1.jar 

[INFO] Copying jersey-common-2.12.jar to D:NworkspaceGithubNJersey-2.x-User-Guid 
e-Demos\demo-1.5\simple-heroku-webapp\target\dependency\jersey-common-2.12.jar 
[INFO] Copying jersey-server-2.12.jar to D:\workspaceGithub\Jersey-2.x-User-Guid 
e-Demos\demo-1.5\simple-heroku-webapp\target\dependency\jersey-server-2.12.jar 
[INFO] Copying jetty-io-9.0.6.v20130930.jar to D:\workspaceGithub\Jersey-2.x-Use 
r-Guide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjetty-io-9.0.6.v20 
130930.jar 

[INFO] Copying jetty-server-9.0.6.v20130930.jar to D:\workspaceGithub\Jersey-2.x 
-User -Guide-Demos\demo-1.5\simple-heroku-webapp\target\dependency\jetty-server -9 
.0.6.v20130930. jar 

[INFO] Copying hk2-locator-2.3.0-b10.jar to D:\workspaceGithub\Jersey-2.x-User-G 
uide-Demos\demo-1.5\simple-heroku-webapp\target \dependency\hk2-locator-2.3.0-b10 
.jar 

[INFO] Copying jetty-util-9.0.6.v20130930.jar to D:\workspaceGithub\Jersey-2.x-U 
ser-Guide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjetty-util-9.0.6 


.V20130930. jar 

[INFO] Copying jetty-http-9.0.6.v20130930.jar to D:\workspaceGithub\Jersey-2.x-U 
ser-Guide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjetty-http-9.0.6 
.V20130930. jar 

[INFO] Copying jersey-container-servlet-2.12.jar to D:NworkspaceGithubNJersey-2. 
x-User -Guide-Demos\demo-1.5\simple-heroku-webapp\target\dependency\jersey-contai 
ner-servlet-2.12.jar 

[INFO] Copying hk2-utils-2.3.0-b10.jar to D:\workspaceGithub\Jersey-2.x-User-Gui 
de-Demos\demo-1.5\simple-heroku-webapp\target\dependency\hk2-utils-2.3.0-b10.jar 


[INFO] Copying jetty-xml-9.0.6.v20130930.jar to D:\workspaceGithub\Jersey-2.x-Us 
er -Guide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjetty-xml-9.0.6.v 
20130930.jar 

[INFO] Copying javax.inject-2.3.0-b10.jar to D:\workspaceGithub\Jersey-2.x-User- 
Guide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjavax.inject-2.3.0-b 
10.jar 

[INFO] Copying jersey-guava-2.12.jar to D:NworkspaceGithubNJersey-2.x-User-Guide 
-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjersey-guava-2.12.jar 
[INFO] Copying aopalliance-repackaged-2.3.0-b10.jar to D:\workspaceGithub\ Jersey 
-2.x-User -Guide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNaopallianc 
e-repackaged-2.3.0-b10.jar 

[INFO] Copying jetty-servlet-9.0.6.v20130930.jar to D:NworkspaceGithubNJersey-2. 
x-User -Guide-Demos\demo-1.5\simple-heroku-webapp\target\dependency\jetty-servlet 
-9.0.6.v20130930. jar 

[INFO] Copying javax.annotation-api-1.2.jar to D:\workspaceGithub\Jersey-2.x-Use 
r -Guide -Demos\demo-1.5\simple-heroku-webapp\target\dependency\javax.annotation-a 
pi-1.2.jar 

[INFO] Copying javax.servlet-3.0.0.v201112011016.jar to D:\workspaceGithub\Jerse 
y-2.x-User -Guide-Demos\demo-1.5\simple-heroku-webapp\target\dependency\javax.ser 
vlet-3.0.0.Vv201112011016. jar 

[INFO] Copying javax.ws.rs-api-2.0.1.jar to D:\workspaceGithub\Jersey-2.x-User-G 
uide-DemosNdemo-1.5Nsimple-heroku-webappNtargetNdependencyNjavax.ws.rs-api-2.0.1 
.jar 

INO) CC LE 
[INFO] BUILD SUCCESS 

ENEON 
[INFO] Total time: 03:17 min 

[INFO] Finished at: 2014-08-30T10:17:48+08:00 

[INFO] Final Memory: 17M/42M 

[ENE ON E socom ances meas sosmeseauscasscqassos 


接 下 来 你 可 以 做 : 


e 改变 项 目 
e 打包 成 WAR 部 署 到 任意 Servlet 容器 
© 或 者 部 署 到 Heroku( 参 见 下 文 1.5.1) 


> = 


提示 : 可 以 执行 mvn clean package jetty:run RA BABA S AKA Jetty FSB 


执行 java -cp target/classes:target/dependency/* com.example.heroku.Main (AB X Jetty 在 


Heroku 的 启动 方式 ) 


1.5.1. Deploy it on Heroku 部 署 在 Heroku 


首先 是 要 注册 Heroku 的 账户 ， 这 里 不 展开 讲 。 可 以 参考 Getting Started with Java on 
Heroku。 当 你 的 Heroku 环 境 准 备 完 毕 后 ， 接 着 看 下 面 的 步骤 : 


首先 给 你 的 项 目 创建 一 个 Git 仓库 : 


$ git init 
Initialized empty Git repository in /.../simple-heroku-webapp/.git/ 


接着 创建 Heroku 的 实例 ， 并 把 远程 引用 添加 到 你 的 Git 仓库 : 


$ heroku create 

Creating simple-heroku-webapp... done, stack is cedar 
http://simple-heroku-webapp.herokuapp.com/ | git@heroku.com:simple-heroku-webapp.git 
Git remote heroku added 


注意 : heroku create 默认 创建 的 实例 名 称 是 一 串 随 机 的 字符 串 类 似 与 tranquil-basin- 
4744 ， 而 不 一 定 是 你 项 目 名 simple-heroku-webapp 。( 译 者 注 : 当然 你 可 以 根据 用 户 自 定义 实 
例 名 称 ， 具 体 的 要 参考 Getting Started with Java on Heroku) 


添加 并 提交 到 你 的 Git 仓库 : 


$ git add src/ pom.xml Procfile system.properties 
$ git commit -a -m "initial commit" 

[master (root-commit) e2b58e3] initial commit 

7 files changed, 221 insertions(+) 

create mode 100644 Procfile 

create mode 100644 pom.xml 

create mode 100644 src/main/java/com/example/MyResource. java 
create mode 100644 src/main/java/com/example/heroku/Main. java 
create mode 100644 src/main/webapp/WEB- INF/web. xml 

create mode 100644 src/test/java/com/example/MyResourceTest.java 
create mode 100644 system.properties 


将 修改 推送 到 Heroku: 


$ git push heroku master 

Counting objects: 21, done. 

Delta compression using up to 8 threads. 

Compressing objects: 100% (11/11), done. 

Writing objects: 100% (21/21), 3.73 KiB | 0 bytes/s, done. 
Total 21 (delta 0), reused 0 (delta 0) 


eddies > Java app detected 
----- > Installing OpenJDK 1.7... done 


----- > Installing Maven 3.0.3... done 
----- > Installing settings.xml... done 
----- > executing /app/tmp/cache/.maven/bin/mvn -B -Duser.home-/tmp/build 992cc747-26d6 
-4800-bdb1-add47b9583cd -Dmaven.repo.local=/app/tmp/cache/.m2/repository -s /app/tmp/c 
ache/.m2/settings.xml -DskipTests=true clean install 
[INFO] Scanning for projects... 
[INFO] 
[ENE OE E assesses seco soneesn sa aanonse sean ELE 
[INFO] Building simple-heroku-webapp 1.0-SNAPSHOT 
[ENEOUR Se oeysre sacs sees ee toes e sem erase Goer sees Snoneoweeneads 
[INFO] 
[INFO] --- maven-clean-plugin:2.4.1:clean (default-clean) @ simple-heroku-webap 


[INFO] 

[INFO] --- maven-resources-plugin:2.4.3:resources (default-resources) @ simple- 
heroku-webapp --- 

[INFO] Using 'UTF-8' encoding to copy filtered resources. 

[INFO] skip non existing resourceDirectory /tmp/build_992cc747-26d6-4800-bdbi-a 
dd47b9583cd/src/main/resources 

[INFO] 

[INFO] --- maven-compiler-plugin:2.5.1:compile (default-compile) @ simple-herok 
u-webapp --- 

[INFO] Compiling 2 source files to /tmp/build 992cc747-26d6-4800-bdbi1-add47b958 
3cd/target/classes 

[INFO] 

[INFO] --- maven-resources-plugin:2.4.3:testResources (default-testResources) @ 

simple-heroku-webapp --- 

[INFO] Using 'UTF-8' encoding to copy filtered resources. 

[INFO] skip non existing resourceDirectory /tmp/build 992cc747-26d6-4800-bdbi-a 
dd47b9583cd/src/test/resources 

[INFO] 

[INFO] --- maven-compiler-plugin:2.5.1:testCompile (default-testCompile) Q simp 
le-heroku-webapp --- 

[INFO] Compiling 1 source file to /tmp/build 992cc747-26d6-4800-bdb1-add47b9583 
cd/target/test-classes 


[INFO] 

[INFO] --- maven-surefire-plugin:2.7.2:test (default-test) Q simple-heroku-weba 
pp --- 

[INFO] Tests are skipped. 

[INFO] 

[INFO] --- maven-war-plugin:2.1.1:war (default-war) Q simple-heroku-webapp --- 


[INFO] Packaging webapp 

[INFO] Assembling webapp [simple-heroku-webapp] in [/tmp/build 992cc747-26d6-48 
00-bdb1-add47b9583cd/target/simple-heroku-webapp] 

[INFO] Processing war project 

[INFO] Copying webapp resources [/tmp/build 992cc747-26d6-4800-bdb1-add47b9583c 
d/src/main/webapp] 

[INFO] Webapp assembled in [88 msecs] 

[INFO] Building war: /tmp/build 992cc747-26d6-4800-bdb1-add47b9583cd/target/sim 
ple-heroku-webapp.war 

[INFO] WEB-INF/web.xml already added, skipping 

[INFO] 

[INFO] --- maven-dependency-plugin:2.1:copy-dependencies (copy-dependencies) Q 


simple-heroku-webapp --- 

[INFO] Copying guava-14.0.1.jar to /tmp/build 992cc747-26d6-4800-bdb1-add47b958 
3cd/target/dependency/guava-14.0.1.jar 

[INFO] Copying javax.annotation-api-1.2.jar to /tmp/build 992cc747-26d6-4800-bd 
b1-add47b9583cd/target/dependency/javax.annotation-api-1.2.jar 

[INFO] Copying validation-api-1.1.0.Final.jar to /tmp/build 992cc747-26d6-4800- 
bdb1-add47b9583cd/target/dependency/validation-api-1.1.0.Final.jar 

[INFO] Copying javax.ws.rs-api-2.0.jar to /tmp/build 992cc747-26d6-4800-bdb1-ad 
d47b9583cd/target/dependency/javax.ws.rs-api-2.0.jar 

[INFO] Copying jetty-http-9.0.6.v20130930.jar to /tmp/build 992cc747-26d6-4800- 
bdb1-add47b9583cd/target/dependency/jetty-http-9.0.6.v20130930. jar 

[INFO] Copying jetty-io-9.0.6.v20130930.jar to /tmp/build 992cc747-26d6-4800-bd 
b1-add47b9583cd/target/dependency/jetty-io-9.0.6.v20130930.jar 

[INFO] Copying jetty-security-9.0.6.v20130930.jar to /tmp/build 992cc747-26d6-4 
800-bdb1-add47b9583cd/target/dependency/jetty-security-9.0.6.v20130930. jar 

[INFO] Copying jetty-server-9.0.6.v20130930.jar to /tmp/build_992cc747-26d6-480 
0-bdbi-add47b9583cd/target/dependency/jetty-server-9.0.6.v20130930. jar 

[INFO] Copying jetty-servlet-9.0.6.v20130930.jar to /tmp/build 992cc747-26d6-48 
00-bdb1-add47b9583cd/target/dependency/jetty-servlet-9.0.6.v20130930.jar 

[INFO] Copying jetty-util-9.0.6.v20130930.jar to /tmp/build 992cc747-26d6-4800- 
bdb1-add47b9583cd/target/dependency/jetty-util-9.0.6.v20130930.jar 

[INFO] Copying jetty-webapp-9.0.6.v20130930.jar to /tmp/build 992cc747-26d6-480 
0-bdbi-add47b9583cd/target/dependency/jetty-webapp-9.0.6.v20130930. jar 

[INFO] Copying jetty-xml-9.0.6.v20130930.jar to /tmp/build 992cc747-26d6-4800-b 
db1-add47b9583cd/target/dependency/jetty-xml-9.0.6.v20130930.jar 

[INFO] Copying javax.servlet-3.0.0.v201112011016.jar to /tmp/build 992cc747-26d 
6-4800-bdb1-add47b9583cd/target/dependency/javax.servlet-3.0.0.v201112011016.jar 

[INFO] Copying hk2-api-2.2.0-b21.jar to /tmp/build_992cc747 -26d6-4800-bdb1i-add4 
7b9583cd/target/dependency/hk2-api-2.2.0-b21.jar 

[INFO] Copying hk2-locator-2.2.0-b21.jar to /tmp/build 992cc747-26d6-4800-bdb1i- 
add47b9583cd/target/dependency/hk2-locator-2.2.0-b21.jar 

[INFO] Copying hk2-utils-2.2.0-b21.jar to /tmp/build 992cc747-26d6-4800-bdb1-ad 
d47b9583cd/target/dependency/hk2-utils-2.2.0-b21.jar 

[INFO] Copying osgi-resource-locator-1.0.1.jar to /tmp/build 992cc747-26d6-4800 
-bdbi-add47b9583cd/target/dependency/osgi-resource-locator-1.0.1.jar 

[INFO] Copying asm-all-repackaged-2.2.0-b21.jar to /tmp/build 992cc747-26d6-480 
0-bdbi-add47b9583cd/target/dependency/asm-all-repackaged-2.2.0-b21.jar 

[INFO] Copying cglib-2.2.0-b21.jar to /tmp/build_992cc747-26d6-4800-bdb1-add47b 
9583cd/target/dependency/cglib-2.2.0-b21.jar 

[INFO] Copying javax.inject-2.2.0-b21.jar to /tmp/build 992cc747-26d6-4800-bdb1i 
-add47b9583cd/target/dependency/javax.inject-2.2.0-b21.jar 

[INFO] Copying jersey-container-servlet-2.5.jar to /tmp/build 992cc747-26d6-480 
0-bdbi-add47b9583cd/target/dependency/jersey-container-servlet-2.5.jar 

[INFO] Copying jersey-container-servlet-core-2.5.jar to /tmp/build 992cc747-26d 
6-4800-bdb1-add47b9583cd/target/dependency/jersey-container-servlet-core-2.5.jar 

[INFO] Copying jersey-client-2.5.jar to /tmp/build 992cc747-26d6-4800-bdb1-add4 
7b9583cd/target/dependency/jersey-client-2.5.jar 

[INFO] Copying jersey-common-2.5.jar to /tmp/build_992cc747 -26d6-4800-bdb1i-add4 
7b9583cd/target/dependency/jersey-common-2.5.jar 

[INFO] Copying jersey-server-2.5.jar to /tmp/build 992cc747-26d6-4800-bdb1-add4 
7b9583cd/target/dependency/jersey-server-2.5.jar 

[INFO] 

[INFO] --- maven-install-plugin:2.3.1:install (default-install) Q simple-heroku 


-webapp --- 

[INFO] Installing /tmp/build 992cc747-26d6-4800-bdb1-add47b9583cd/target/simple 
-heroku-webapp.war to /app/tmp/cache/.m2/repository/com/example/simple-heroku-webapp/1 
.0- SNAPSHOT/simple-heroku-webapp-1.0-SNAPSHOT.war 

[INFO] Installing /tmp/build 992cc747-26d6-4800-bdb1-add47b9583cd/pom.xml to /a 
pp/tmp/cache/.m2/repository/com/example/simple-heroku-webapp/1.0-SNAPSHOT/simple-herok 
u-webapp-1.0-SNAPSHOT. pom 

PENEONME E 

[INFO] BUILD SUCCESS 

ENEON ouemmesosenossoureesous 

[INFO] Total time: 45.861s 

[INFO] Finished at: Mon Dec 09 19:51:34 UTC 2013 

[INFO] Final Memory: 17M/514M 

ENEON D ELLE 
----- > Discovering process types 

Procfile declares types -> web 


----- > Compiled slug size: 75.9MB 
----- > Launching... done, v6 
http://simple-heroku-webapp.herokuapp.com deployed to Heroku 


To git@heroku.com:simple-heroku-webapp.git 
* [new branch] master -> master 


现在 你 可 以 访问 你 的 应 用 了 。 本 例子 是 http://simple-heroku- 
webapp.herokuapp.com/myresource 


1.6. Exploring Other Jersey Examples 探索 
其 他 例子 


在 上 几 节 内 容 ， 我 们 快速 的 接触 了 Jersey。 请 参阅 用 户 指南 的 其 他 部 分 以 了 解 更 多 关于 
Jersey 和 JAX-RS. 即 使 我 们 尽力 覆盖 尽 可 能 多 的 用 户 指南 ， 但 还 是 无 法 解决 你 所 有 的 问题 。 
在 这 种 情况 下 ， 深 入 查看 我 们 的 例子 ， 可 能 能 给 你 的 项 目 提供 了 额外 的 技巧 和 提示 。 


Jersey 的 代码 库 包 含 了 很 多 Jersey 和 JAX-RS 的 特性 。 随 意 浏 览 Jersey 的 例子 代码 。 也 可 
以 在 此 下 载 离线 包 。 

EAE: 上 文 所 有 例子 的 源码 ， 可 以 在 https://github.com/waylau/Jersey-2.x-User-Guide- 
Demos 获取 到 。 


Chapter 2. Modules and dependencies 7% 
块 和 依赖 


2.1. Java SE Compatibility 5 Java SE 兼容 
性 


2.6 以 前 的 版 本 ，Jersey 由 Java SE 6 编译 。2.7 版 本 后 发 生 了 变化 。 现 在 几乎 所 有 的 Jersey 
组 件 用 Java SE 7 目标 编译 。 这 意味 着 ， 如 果 要 使 用 最 新 的 Jersey ， 你 将 至 少 需要 Java SE 7 
能 够 编译 并 运行 你 的 应 用 程序 9 只 有 core-common 和 core-client 模块 仍然 需要 Java SE 6 
编译 。 


2.2. Introduction to Jersey dependencies 
4y 48 Jersey 5 1K i 


Jersey 的 创建 、 组 装 和 安装 都 是 使 用 Apache Maven， 非 快照 的 Jersey 都 部 署 到 了 Maven 
中 央 库 。 他 也 部 署 在 了 Java.Net Maven repositories， 包 括 带 有 快照 的 版 本 。 当 然 如 果 要 查看 
最 新 的 版 本 也 可 以 从 Java.Net Maven repositories # H » 


一 个 使 用 Jersey 的 应 用 ， 依 赖 于 Jersey 的 模块 ， 但 是 如 果 使 用 了 第 三 方 模块 ， 那 么 Jersey 
可 能 反 过 来 依赖 第 三 方 模块 。Jersey 是 插件 化 的 组 件 结构 ， 所 以 不 同 的 应 用 可 能 依赖 不 同 的 
模块 。 


开发 者 使 用 Maven 或 者 Maven 相关 的 构建 系统 在 他 们 的 应 用 里 面 ， 比 使 用 Ant 或 者 其 他 构 
建 系统 更 加 容易 管理 他 们 的 依赖 。 这 个 文档 就 是 要 解释 使 用 maven 或 者 不 使 用 maven 在 他 
们 的 应 用 里 怎么 依赖 Jersey 的 模块 。Ant 开发 者 请 参阅 Ant Tasks for Maven 


2.3. Common Jersey Use Cases 常见 
Jersey #| 


2.3.1 KF Servlet 的 GlassFish 应 用 


如 果 你 使 用 GlassFish 应 用 服务 ， 那 么 你 不 需要 打包 任何 东西 ， 所 有 的 一 切 都 已 经 包含 在 其 
中 了 。 你 只 需要 在 你 的 应 用 中 声明 依赖 使 用 JAX-RS API 即 可 。 


<dependency> 
<groupId>javax.ws.rs</groupId> 
<artifactId>javax.ws.rs-api</artifactId> 
<version>2.0.1</version> 
<scope>provided</scope> 

</dependency> 


如 果 你 使 用 特定 的 功能 ， 那 么 直接 使 用 特定 的 Jersey 依赖 即 可 : 


<dependency> 
<groupId>org.glassfish.jersey.containers</groupId> 
<artifactId>jersey-container-servlet</artifactId> 
<version>2.23.2</version> 
<scope>provided</scope> 

</dependency> 


<dependency> 
«groupId»org.glassfish.jersey.corec/groupId» 
<artifactId>jersey-client</artifactId> 
<version>2.23.2</version> 
<scope>provided</scope> 

</dependency> 


2.3.2 KT Servlet 的 服务 端 应 用 


以 下 依赖 可 以 应 用 于 没有 集成 任何 JAX-RS 实现 的 应 用 服务 器 (servlet 容器 ) 。 需 要 在 部 署 
的 应 用 里 面包 含 JAX-RS API 和 Jersey 的 实现 。 


<dependency> 
<groupId>org.glassfish.jersey.containers</groupId> 
<!-- if your container implements Servlet API older than 3.0, use "jersey-containe 

r-servlet-core" --> 
<artifactId>jersey-container -servlet</artifactId> 
<version>2.23.2</version> 

</dependency> 

<!-- 仅 使 用 JAX-RS Client 时 添加 --> 

<dependency> 
<groupId>org.glassfish.jersey.core</groupId> 
<artifactId>jersey-client</artifactId> 
<version>2.23.2</version> 

</dependency> 


2.3.3 运行 于 JDK 的 客户 端 应 用 


在 JDK 运行 的 应 用 ， 是 否 使 用 JAX-RS 中 客户 端的 规范 完全 取决 于 客户 。 有 各 种 不 同 的 附加 
模块 可 以 被 添加 ， 例 如 像 grizzly ` Apache 或 jetty 等 连接 器 ( 见 下 面 依赖 ) ° Jersey FP 35 
在 JDK 默认 运行 (HttpUrlConnection) 。 更 多 的 细节 可 以 参见 Chapter 5, Client API 。 


<dependency> 
<groupId>org.glassfish.jersey.core</groupId> 
<artifactId>jersey-client</artifactId> 
<version>2.23.2</version> 

</dependency> 


目前 可 用 的 连接 器 : 


<dependency> 
<groupId>org.glassfish.jersey.connectors</groupId> 
<artifactId>jersey-grizzly-connector</artifactId> 
<version>2.23.2</version> 

</dependency> 


<dependency> 
«groupId»org.glassfish.jersey.connectors«/groupId» 
<artifactId>jersey-apache-connector</artifactId> 
<version>2.23.2</version> 

</dependency> 


<dependency> 
<groupiId>org.glassfish.jersey.connectors</groupId> 
<artifactId>jersey-jetty-connector</artifactId> 
<version>2.23.2</version> 

</dependency> 


" 


2.3.4 服务 器 端 应 用 支持 的 容器 


除了 标准 的 JAX-RS 基于 Servlet 的 部 署 (Servlet 2.5 及 以 上 版 本 ) ，Jersey 对 下 面容 器 提供 
可 编程 的 部 署 环境 : Grizzly 2 (HTTP 和 Servlet) ^ JDK HTTP 服 务 器 、 简 单 的 HTTP 服务 


aa 


&& » Jetty HTTP 服务 器 。 本 章 介 绍 只 需要 maven 依赖 ， 更 多 的 内 容 见 Chapter 4. Application 
Deployment and Runtime Environments 应 用 部 署 和 运行 时 环境 


<dependency> 
<groupId>org.glassfish.jersey.containers</groupId> 
<artifactId>jersey-container-grizzly2-http</artifactId> 
<version>2.23.2</version> 

</dependency> 


<dependency> 
<groupiId>org.glassfish.jersey.containers</groupId> 
<artifactId>jersey-container-grizzly2-servlet</artifactId> 
<version>2.23.2</version> 

</dependency> 


<dependency> 
<groupId>org.glassfish.jersey.containers</groupId> 
<artifactId>jersey-container -jdk-http</artifactId> 
<version>2.23.2</version> 

</dependency> 


<dependency> 
<groupiId>org.glassfish.jersey.containers</groupId> 
<artifactId>jersey-container-simple-http</artifactId> 
<version>2.23.2</version> 

</dependency> 


<dependency> 
«groupId»org.glassfish.jersey.containers«c/groupId» 
«artifactId»jersey-container-jetty-http«/artifactId» 
<version>2.23.2</version> 

</dependency> 


<dependency> 
«groupId»org.glassfish.jersey.containers«c/groupId» 
<artifactId>jersey-container-jetty-servlet</artifactId> 
<version>2.23.2</version> 

</dependency> 


2.4. List of modules 模块 列表 


T Jersey - RESTful Web Services in Java. 


T Jersey 


RESTful Web Services in Java. 


About 


Developing RESTful Web services that seamlessly support exposing your 
data in a variety of representation media types and abstract away the low- 
level details of the client-server communication is not an easy task without a 
good toolkit. In order to simplify development of RESTful Web services and 
their clients in Java, a standard and portable JAX-RS API has been 
designed. Jersey RESTful Web Services framework is open source, 
production quality, framework for developing RESTful Web Services in Java 
that provides support for JAX-RS APIs and serves as a JAX-RS (JSR 311 & 
JSR 339) Reference Implementation. 


Jersey framework is more than the JAX-RS Reference Implementation. 
Jersey provides it's own API that extend the JAX-RS toolkit with additional 
features and utilities to further simplify RESTful service and client 
development. Jersey also exposes numerous extension SPIs so that 
developers may extend Jersey to best suit their needs. 


Goals of Jersey project can be summarized in the following points: 


e Track the JAX-RS API and provide regular releases of production quality 
Reference Implementations that ships with GlassFish; 

e Provide APIs to extend Jersey & Build a community of users and 
developers; and finally 

e Make it easy to build RESTful Web services utilising Java and the Java 
Virtual Machine. 


The latest stable release of Jersey is 2.27. 


© Get Started & 


下 面 的 章节 提供 所 有 Jersey 模块 和 与 各 自 的 二 进 制 文件 链接 的 依赖 关系 的 概述 〈 点 击 模块 名 
称 可 以 得 到 下 载 该 模块 的 链接 ) 。 
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Chapter 3. JAX-RS Application, Resources 
and Sub-Resources 关于 JAX-RS 应 用 ， 资 源 
和 子 资源 

本 章 呈 现 JAX-RS 核心 概念 -资源 和 子 资源 的 概述 。 

JAX-RS 2.0 的 JavaDoc 文档 可 以 在 这 里 找到 。 


JAX-RS 2.0 规范 草案 可 以 在 这 里 找到 。 


3.1. Root Resource Classes 根 资 源 类 


Root Resource Classes 是 带 有 @PATH 注解 的 ， 包 含 至 少 一 个 @PATH 注解 的 方法 或 者 方 
法 带 有 @GET ` @PUT ` @POST ` @DELETE 资源 方法 指示 器 的 POJO。 资 源 方法 是 带 有 
资源 方法 指示 器 (resource method designator) 注解 的 方法 。 这 一 节 就 是 展示 如 何 使 用 Java 
对 象 内 的 注解 创建 一 个 Jersey 的 RESTful 服务 。 


下 面 这 段 代 码 就 是 一 个 带 有 JAX-RS 注解 的 简单 示例 ， 可 以 从 这 里 下 载 。 


Example 3.1. 简单 hello world 根 资源 类 例子 


package org.glassfish.jersey.examples.helloworld; 


import javax.ws.rs.GET; 
import javax.ws.rs.Path; 
import javax.ws.rs.Produces; 


@Path("helloworld" ) 
public class HelloWorldResource { 
public static final String CLICHED_MESSAGE = "Hello World!"; 


@GET 
@Produces("text/plain") 
public String getHello() { 


return CLICHED MESSAGE; 
} 


下 面 看 下 JAX-RS 里 面 的 几 个 注解 


3.1.1. @Path 


@PATH 是 一 个 URI 的 相对 路 径 ， 在 上 面 的 例子 中 ， 设 置 的 是 本 地 的 URI 的 /helloworld 。 这 
事 一 个 非常 简单 的 关于 @PATH 的 例子 ， 更 有 用 的 是 你 可 以 诅 入 变量 到 URIs 里 面 

URI 的 路 径 模版 是 由 URIs 和 嵌入 URI 语法 的 变量 组 成 。 变 量 在 运行 时 将 会 被 匹配 到 的 URI 
的 那 部 分 多 代替 。 例 如 下 面 的 @Path 注解 


@Path("/users/{username}") 


按照 这 种 类 型 的 例子 ， 一 个 用 户 会 方便 的 填写 他 的 名 字 ， 那 么 Jersey 服务 器 也 会 按照 这 个 
UIR 路 径 模 板 响应 到 这 个 请 求 。 例 如 : 用 户 输 入 了 名 字 “Galileo”， 那 么 服务 器 就 会 响应 


http://example.com/users/Galileo ° 
为 了 接收 到 用 户 名 变量 ，@PathParam 用 在 接收 请 求 的 方法 的 参数 上 ， 例 如 : 


Example 3.2. 指定 的 URI 路 径 参 数 


@Path("/users/{username}") 


public class UserResource { 
@GET 
@Produces("text/xml") 


public String getUser(@PathParam("username") String userName) { 


} 


它 规 定 匹 配 正 则 表达 式 式 要 精确 到 大 小 写 的 ， 如 果 卉 写 的 话 会 覆盖 默认 的 表达 式 [m] ， 
例如 


@Path("users/{username: [a-zA-Z][a-zA-Z 0-9]*)") 
这 个 正则 表达 式 匹 配 由 大 小 写字 符 、 横 杠 和 数字 组 成 的 字符 囊 ， 如 果 正 则 校 验 不 通过 ， 则 返 
回 404 (没有 找到 资源 ) © 


一 个 @Path 的 内 容 是 否 以 "开头 都 没有 区 别 ， 同 样 是 否 以 "结尾 也 没有 什么 区 别 


3.1.2. @GET, @PUT, @POST, @DELETE, ... 
(HTTP 方法 ) 


@GET, @PUT, @POST, @DELETE, Ma XJAX-RS 定义 的 注解 ， 它 非常 类 似 与 HTTP 
的 方法 名 。 在 上 面 的 例子 中 ， 这 些 注解 是 通过 HTTP 的 GET 方法 实现 的 。 资 源 的 响应 就 是 
HTTP 的 响应 。 


下 面 这 个 例子 是 存储 服务 的 一 个 片段 ， 是 使 用 PUT 方法 处 理 创 建 或 者 修改 存储 容器 : 


Example 3.3. PUT 方法 


@PUT 
public Response putContainer() { 
System.out.println("PUT CONTAINER " + container); 


URI uri = urilInfo.getAbsolutePath(); 
Container c = new Container(container, uri.toString()); 


Response r; 
if (!MemoryStore.MS.hasContainer(c)) { 
r = Response.created(uri).build(); 
) else { 
r = Response.noContent( ).build(); 


} 


MemoryStore.MS.createContainer(c); 
return r; 


如 果 没 有 明确 的 定义 的 话 ，JAX-RS 运行 的 时 候 默 认 支 持 HEAD fe OPTIONS 方法 。HEAD 
运行 时 将 调用 get 方法 的 实现 (如果 存在 ) 和 忽略 响应 实体 〈 如 果 设 置 ) 。 一 个 响应 返回 
OPTIONS 的 方法 取决 于 所 要 求 的 媒体 类 型 在 头 文件 中 'Accept! 的 定义 。 OPTIONS 方法 可 以 
返回 一 组 支持 资源 的 方法 在 头 文件 中 'Allow' 或 返回 WADL 文件 的 进行 设置 。 更 多 信息 见 
https://jersey.java.net/documentation/latest/wadl.html*¥ ° 


3.1.3. @Produces 


@Produces 是 定义 返回 值 给 客户 端的 MIME 媒体 类 型 。 在 下 面 这 个 例子 里 面 ， 将 会 返回 一 个 
对 应 于 text/plain 的 MIME 媒体 类 型 。@Produces 既 可 以 应 用 在 类 上 ， 也 可 以 作用 于 方法 
上 。 这 里 是 一 个 例子 : 


Example 3.4. 指定 输出 文件 的 MIME 类 型 


@Path("/myResource") 
@Produces("text/plain") 
public class SomeResource { 

@GET 

public String doGetAsPlainText() { 


} 
@GET 


QProduces("text/html") 
public String doGetAsHtml() { 


} 


这 个 doGetAsPlainText 方法 默认 使 用 类 水 平 的 @Produces 注解 内 容 ， 也 就 是 text/plain 

。 而 doGetAsHtml 方法 使 用 方法 水 平 上 的 @Produces， 也 就 是 text/html 。 也 就 是 说 方法 水 
平 层面 的 @Produces 会 覆盖 类 层面 的 @Produces。 

如 果 一 个 资源 类 是 能 够 生产 多 个 MIME 媒体 类 型 ,资源 的 方法 的 响应 将 会 对 应 对 于 客户 端 来 说 
最 可 接受 的 媒体 类 型 。HTTP 请 求 头 部 宣布 接受 什么 是 最 容易 被 接受 的 。 例 如 ， 如 果 接 受 头 部 
是 Accept: text/plain 然后 dogetasplaintext 方法 会 被 调用 。 如 果 接 受 标 题 是 Accept: 
text/plain;q=0.9, text/htm ? 即 客 户 可 以 接受 text/plain fe text/html ， 但 更 容易 接收 后 
者 的 媒体 类 型 ， 然 后 dogetashtml 方法 会 被 调用 。 


@Produces 可 以 定义 多 个 返回 类 型 ， 例 如 : 


Example 3.5. 使 用 多 个 返回 类 型 


@GET 
@Produces({"application/xml", "application/json"}) 
public String doGetAsXmlOrJson() { 


} 


无 论 application/xml 或 者 application/json 哪个 匹配 上 了 ， 都 会 执行 doGetAsXmlOrJson ， 
如 果 两 个 都 匹配 了 ， 那 么 会 选择 首先 匹配 的 那个 。 

服务 器 也 可 选 的 指定 个 别 媒 体 类 型 的 品质 因数 。 这 些 是 客户 端的 决定 的 如 何 才 是 可 接受 的 。 
例如 : 


Example 3.6. 服务 器 端 内 容 协商 


@GET 
@Produces({"application/xml; qs=0.9", "application/json"}) 
public String doGetAsXmlOrJson() { 


} 
在 上 面 的 示例 ， 如 果 客 户 端 是 接受 application/xml 或 者 application/json ， 那么 服务 器 总 
是 发 送 application/json ， 因为 application/xml 有 一 个 较 低 的 品质 因数 。 


上 面 的 例子 是 指明 确 清楚 的 MME 媒体 类 型 。 最 好 让 它 用 常量 来 表示 ， 这 样 可 能 会 降低 印刷 
HIA o BAA IL MediaType 的 常量 字段 值 。 


3.1.4. @Consumes 


@Consumes 注 释 是 用 来 指定 表示 可 由 资源 消耗 的 MIME 媒体 类 型 。 上 面 的 例子 可 以 修改 设 
置 如 下 : 


Example 3.7. 指定 输入 MIME 类 型 : 


@POST 

@Consumes("text/plain" ) 

public void postClichedMessage(String message) { 
// Store the message 


} 


在 这 个 例子 中 ， 该 Java 方法 将 消耗 表示 确定 的 MIME 媒体 类 型 text/plain 。 注 意 资 源 的 方 
法 返回 void 。 这 意味 着 没有 内 容 返回 ， 而 是 一 个 204 状态 码 响应 (204 是 指 "无 内 容 ") 将 返回 
到 客户 端 。 


@Consumes 既 可 以 应 用 在 类 的 水 平 上 ， 也 可 以 作用 与 方法 的 水 平 ， 而 且 声 明 可 以 不 只 一 种 类 


型 。 


3.2. Parameter Annotations (@*Param) # 
注解 


ee 
J @Path 之 后 ， 通 过 @PathParam 来 获取 URL 请 求 中 的 路 径 参 数 。 


@QueryParam 用 于 从 请 求 URL 的 查询 组 件 中 提取 查询 参数 。 下 面 的 例子 


Example 3.8. 查询 参数 


@Path("smooth") 

@GET 

public Response smooth( 
@DefaultValue("2") @QueryParam("step") int step, 
@DefaultValue("true") @QueryParam("min-m") boolean hasMin, 
@DefaultValue("true") QQueryParam("max-m") boolean hasMax, 
@DefaultValue("true") @QueryParam("last-m") boolean hasLast, 
@DefaultValue("blue") @QueryParam("min-color") ColorParam minColor, 
@DefaultValue("green") @QueryParam("max-color") ColorParam maxColor, 
@DefaultValue("red") @QueryParam("last-color") ColorParam lastColor) { 


如 果 step 的 参数 存在 的 话 ， 那 么 附 值 给 它 ， 否 则 默认 是 @DefaultValue 定 义 的 值 2。 如 果 
step 的 内 容 不 是 32 位 的 整 型 ， 那 么 会 返 Mos o 


用 户 定 义 了 一 个 Java 类 型 ColorParam， 实 现 如 下 : 


Example 3.9. 自 定 义 Java 类 型 用 作 消 耗 请 求 的 参数 


public class ColorParam extends Color { 


public ColorParam(String s) { 
super (getRGB(s)); 


} 
private static int getRGB(String s) { 
if (s.charAt(0) == '#') { 
try { 


Color c = Color.decode("Ox" + s.substring(1)); 
return c.getRGB(); 

} catch (NumberFormatException e) { 
throw new WebApplicationException( 400); 


j 
) else { 


try { 
Field f - Color.class.getField(s); 


return ((Color)f.get(null)).getRGB(); 
) catch (Exception e) { 
throw new WebApplicationException(400); 


j 


一 般 的 ，Java 方法 的 参数 类 型 的 可 能 是 : 


e 一 个 原始 类 型 ; 

© 有 一 个 接收 一 个 字符 串 参 数 的 构造 函数 ; 

e 有 一 个 命名 为 fromstring 或 valueOf 的 静态 方法 ， 用 于 接收 字符 串 参 数 ， 例 
如 Integer .valueOf (String) 和 java.util.UUID.fromString(String) ; 

e 有 一 个 javax.ws.rs.ext.ParamConverterProvider 的 JAX-RS 扩展 SPI 的 注册 实现 ， 将 返 
回 javax.ws.rs.ext.ParamConverter 能 转化 “字符 串 ? 类 型 的 实例 ; 

e AList, Set 或 者 SortedList, 且 在 下 满足 上 面 2 或 者 3 个 条 件 时 ， 将 会 是 List、Set 或 者 
SortedSet。 这 样 的 集合 是 只 读 的 。 


有 时 参数 可 以 包含 相同 名 称 的 多 个 值 。 如 果 是 这 样 的 话 ， 上 面 第 5 条 可 以 用 来 获得 所 有 的 值 。 


如 果 @DefaultValue 不 与 QQueryParam 联 合 使 有 用， 查询 参数 在 请 求 中 如 果 不 存在 ，List、 
Set 或 者 SortedSet 类 型 将 会 是 空 值 集合 ， 对 象 类 型 将 为 室 ，Java 的 定义 默认 为 原始 类 型 。 


@PathParam 和 其 他 参数 注解 

@MatrixParam ` @HeaderParam ` @CookieParam ` @FormParam 遵循 与 @QueryParam 
一 样 的 规则 。@MatrixParam 从 URL 路 径 提 取信 息 。@HeaderParam 从 HTTP 头 部 提取 信 
息 。@CookieParam 从 关联 在 HTTP 头 部 的 cookies 里 提取 信息 。 


@FormParam 稍 有 特殊 ， 因 为 它 提 取信 息 ， 先 是 请 求 所 表示 的 MIME 媒 体 类 型 为 
application/x-www-form-urlencoded ， 并 且 符 合 指定 的 HTML 编码 的 形式 ， 正 如 这 里 所 描述 
的 。 此 参数 提取 对 于 HTML 表单 请 求 是 非常 有 用 的 ， 例 如 从 发 布 的 表单 数据 中 提取 名 称 是 
name 的 参数 信息 : 


Example 3.10. HTML 表 格 处 理 


@POST 

@Consumes("application/x-www- form-urlencoded" ) 

public void post(@FormParam("name") String name) { 
// Store the message 


如 果 需 要 通过 查询 路 径 参 数 ， 从 Map 参数 名 称 获取 值 ， 做 法 以 下 : 


Example 3.11. 从 查询 参数 或 者 路 径 获 取 Map 


@GET 

public String get(@Context UriInfo ui) { 
MultivaluedMap<String, String» queryParams = ui.getQueryParameters(); 
MultivaluedMap<String, String» pathParams = ui.getPathParameters(); 


header 和 cookie 参数 用 法 如 下 : 


Example 3.12. 从 头 部 参数 获取 Map 


@GET 

public String get(@Context HttpHeaders hh) { 
MultivaluedMap<String, String» headerParams = hh.getRequestHeaders(); 
Map<String, Cookie» pathParams = hh.getCookies(); 


@Context 一 般 可 以 用 于 获得 一 个 Java 类 型 关联 请 求 或 响应 的 上 下 文 。 
因为 form 表单 参数 (不 像 其 他 消息 的 一 部 分 ) 是 实体 ， 做 法 如 下 : 


Example 3.13. form 表单 参数 获取 Map 
@POST 
@Consumes("application/x-www-form-urlencoded") 


public void post(MultivaluedMap<String, String> formParams) { 
// Store the message 


就 是 说 ， 不 需要 @Context 注 解 。 


另 一 种 注入 是 @BeanParam 允许 注入 上 述 参 数 到 一 个 bean. 。 一 个 bean 注 明 @BeanParam 
含 任何 属性 和 适当 的 参数 注解 ( 像 @PathParam) 将 由 预期 的 相应 请 求 值 初 始 化 (如果 这 些 
领域 在 资源 类 ) 。 然 后 ， 跟 将 请 求 值 ( 像 路 径 参 数 ) 注入 到 一 个 构造 函数 参数 或 类 属性 不 同 
的 是 ，@BeanParam 可 以 用 于 注入 这 种 bean 到 资源 或 资源 的 方法 。@BeanParam 就 是 用 这 
样 的 方式 聚集 更 多 的 请 求 参 数 为 一 个 单一 的 bean 的 情况 。 


Example 3.14. @BeanParam 用 法 


public class MyBeanParam { 
@PathParam("p") 
private String pathParam; 


@MatrixParam("m") 

@Encoded 
@DefaultValue("default") 
private String matrixParam; 


@HeaderParam("header" ) 
private String headerParam; 


private String queryParam; 


public MyBeanParam(@QueryParam("q") String queryParam) { 
this.queryParam = queryParam; 


} 


public String getPathParam() { 
return pathParam; 


} 


Example 3.15. 将 MyBeanParam 以 参数 形式 注入 : 


@POST 
public void post(@BeanParam MyBeanParam beanParam, String entity) { 

final String pathParam = beanParam.getPathParam(); // contains injected path param 
eter "p" 


s | & a 1 @PathParam ` @QueryParam ` @MatrixParam4* @HeaderParam 集 中 在 一 个 
bean 里 面 。 里 面 的 bean 注射 规则 如 上 这 些 注射 相同 。@DefaultValue 是 用 来 定义 矩阵 参数 
的 默认 值 。 同 时 @Encoded 注 释 都 有 同样 的 行为 ， 如 果 它 是 用 来 在 资源 的 方法 直接 注入 。 将 
bean 参数 注入 到 注解 为 @Singleton 的 资源 类 字段 是 不 允许 的 《注射 方法 的 参数 必须 替 
换 ) 。 


@BeanParam 可 以 包含 所 有 的 注入 参数 
(@PathParam ` @QueryParam ` @MatrixParam ` @HeaderParam ^ (Q)CookieParam ^ 
@FormParam )° 


多 个 bean 可 以 被 注入 到 一 个 资源 或 方法 的 参数 ， 即 使 他 们 注入 相同 的 请 求 值 。 例 如 ， 以 下 是 
可 能 的 : 


Example 3.16. 多 个 bean 注入 到 一 个 资源 或 方法 


@POST 
public void post(@BeanParam MyBeanParam beanParam, @BeanParam AnotherBean anotherBean, 
@PathParam("p") pathParam, 
String entity) { 
// beanParam.getPathParam() == pathParam 


3.3. Sub-resources 子 资 源 


@Path 可 以 用 在 类 上 ， 这 样 的 类 称 为 根 资源 类 。 也 可 以 被 用 来 根 资源 类 的 方法 上 。 这 使 得 许 
多 资源 的 方法 被 组 合 在 一 起 ， 能 够 被 重用 。 


第 一 种 方法 ，@Path 是 用 在 资源 的 方法 上 ， 这 类 方法 是 被 称 为 子 资源 方法 (sub-resource 
method) 。 下 面 的 例子 显示 一 个 资源 类 jmaki 后 端 签名 方法 的 示例 : 


Example 3.17. 子 资 源 方 法 


@Singleton 
@Path("/printers") 
public class PrintersResource { 


@GET 
@Produces({"application/json", "application/xml")) 
public WebResourceList getMyResources() { ... } 


@GET @Path("/list") 
@Produces({"application/json", "application/xml"}) 
public WebResourceList getListOfPrinters() { ... } 


@GET @Path("/jMakiTable" ) 
@Produces("application/json" ) 
public PrinterTableModel getTable() { ... } 


@GET @Path("/jMakiTree") 
@Produces("application/json" ) 
public TreeModel getTree() ( ... } 


@GET @Path("/ids/{printerid}") 
@Produces({"application/json", "application/xml")) 
public Printer getPrinter(QPathParam("printerid") String printerId) { ... } 


QPUT QPath("/ids/(printerid]") 
@Consumes({"application/json", "application/xml")) 
public void putPrinter(@PathParam("printerid") String printerId, Printer printer) 


F aag) 


@DELETE @Path("/ids/{printerid}") 
public void deletePrinter(@PathParam("printerid") String printerId) { ... } 


如 果 请 求 URL 的 路 径 是 “printers”， 那 么 资源 的 方法 中 没有 @Path 注解 的 将 被 选择 。 如 果 请 
RAY URL 请 求 的 路 径 是 “printers/list”， 则 首先 在 根 资源 类 中 进行 匹配 ， 然 后 在 子 资源 中 ， 相 
匹配 的 方法 “list" 将 被 选择 ， 在 这 种 情况 下 ， 子 资源 方法 是 getListOfPrinters 。 因 此 ， 在 这 个 例 


子 中 的 URL 路 径 将 会 分 层 匹 


ee tt 能 用 在 那些 没有 用 资源 指示 器 ( 像 @GET 或 者 @POST) 注解 的 方法 
这 种 方法 被 称 为 子 资源 定位 器 (sub-resource locator) 。 下 面 的 示例 显示 一 个 根 资源 类 
mie ee ee 


Example 3.18. 子 资 源 定 位 器 


QPath("/item") 
public class ItemResource { 
@Context Urilnfo uriInfo; 


QPath("content") 


public ItemContentResource getItemContentResource() { 
return new ItemContentResource(); 


QGET 
@Produces("application/xml" ) 
public Item get() { ... } 


public class ItemContentResource { 


@GET 
public Response get() { ... } 


@PUT 

@Path("{version}") 

public void put(@PathParam("version") int version, 
@Context HttpHeaders headers, 
byte[] in) { 


根 资源 类 ItemResource 包含 子 资源 定位 方法 ee ， 用 于 返回 一 个 新 的 
资源 类 。 如 果 请 求 URL 的 路 径 是 “tem/content"， 首 先 在 根 资源 进行 匹配 ， 而 后 则 子 资源 定位 
器 将 会 匹配 和 调用 ， 它 将 返回 ItemContentResource 资源 类 的 一 1 Een 。 子 资源 定位 器 使 得 


资源 类 的 能 够 被 重用 。 方 法 上 可 以 有 空 路 径 的 @Path 注 解 ， 如 @Path("/") 或 @Path(")， 这 
意味 着 子 资 源 定位 器 匹配 了 一 个 封闭 的 资源 路 径 匹 配 (无 子 资源 的 路 径 ) o 


Example 3.19. 空 路 径 的 子 资源 定位 器 


QPath("/item") 
public class ItemResource { 


QPath("/") 
public ItemContentResource getlItemContentResource() { 
return new ItemContentResource(); 


上 面 例子 ， 子 资源 定位 器 方法 getltemContentResource 将 会 匹配 请 求 路 径 


AT 


x "litem/locator" X, "/item" » 


此 外 ， 由 于 资源 类 中 由 子 资 源 定位 器 在 运行 时 返回 处 理 结果 ， 从 而 支持 多 态 性 。 子 资源 定位 
器 返回 怎么 样 的 不 同 的 子 类 型 ， 这 取决 于 请 求 (例如 一 次 资源 定位 器 可 以 返回 怎么 样 的 子 类 
型 取决 于 不 同 的 认证 请 求 ) 。 例 如 ， 下 面 的 子 资源 定位 器 是 有 效 的 : 


Example 3.20. 子 资 源 定 位 器 返回 子 类 型 


QPath("/item") 
public class ItemResource { 


QPath("/") 
public Object getItemContentResource() { 
return new AnyResource( ); 


注意 ， 运 行 时 将 没有 生命 周期 管理 或 执行 任何 字段 注入 到 子 资源 定位 方法 返回 的 实例 。 这 是 
雪人 周期 是 什么 。 如 果 必 需要 运行 时 管理 子 资源 作为 标准 的 资源 ， 
类 应 按 以 下 示例 返 


Example 3.21. 从 类 中 创建 子 资源 定位 器 


import javax.inject.Singleton; 


QPath("/item") 
public class ItemResource { 
QPath("content") 
public Class«ItemContentSingletonResource» getItemContentResource() { 
return ItemContentSingletonResource.class; 


Singleton 
public class ItemContentSingletonResource { 
// this class is managed in the singleton life cycle 


JAX-RS 资源 默认 情况 下 ， 在 每 个 请 求 范围 受到 管理 ， 这 意味 着 为 每 个 请 求 创建 新 的 资源 。 在 
这 个 例子 中 ， javax.inject.Singleton 注解 是 说 ， 资 源 将 是 单 例 模式 ， 不 受 请 求 范围 管理 。 子 
资源 定位 方法 返回 一 个 类 ， 这 意味 着 运行 时 将 托管 资源 的 实例 及 其 生命 周期 。 相 反 ， 如 果 方 
法 返回 的 是 实例 ， 那 么 注释 将 没有 效果 ， 返 回 的 实例 将 被 使 用 。 


子 资源 定位 器 也 可 以 返回 一 个 programmatic resource model (可 编程 的 资源 模型 )。 更 多 关于 
可 编程 资源 模型 的 构建 ， 请 看 resource builder 章节 内 容 。 下 面 的 示例 显示 子 资源 定位 方法 
返回 的 非常 简单 的 资源 。 


Example 3.22. 子 资 源 定 位 返回 资源 模型 


import org.glassfish.jersey.server.model.Resource; 


QPath("/item") 
public class ItemResource { 


@Path("content" ) 
public Resource getItemContentResource() { 


return Resource. from(ItemContentSingletonResource.class); 


上 面 的 代码 与 之 前 的 例子 有 同样 的 效果 。Resource 是 一 种 来 自 
ItemContentSingletonResource 构造 的 简单 的 资源 。 只 要 是 有 效 的 资源 ， 都 可 以 返回 更 复杂 
的 编程 化 资源 。 


3.4. Life-cycle of Root Resource Classes 
根 资源 类 生命 周期 
默认 情况 下 ， 根 资源 类 的 生命 周期 是 每 个 请 求 ， 即 一 根 资源 类 的 新 实例 在 每 次 请 求 的 URI 路 径 


匹配 根 资源 时 创建 。 利 用 构造 函数 和 域 可 以 构造 一 个 很 自然 的 编程 模型 ， 如 前 一 节 中 显示 的 
SparklinesResource 类 的 构造 函数 ) 而 无 需 关 心 对 同一 资源 的 多 个 并 发 请 求 。 


总 的 来 说 这 不 太 可 能 的 成 为 性 能 问题 的 原因 。 近 年 来 ， 类 的 构造 以 及 JVM 的 GC 已 大 大 改 
善 ， 在 服务 和 处 理 HTTP 请 求 并 返回 HTTP 响应 中 ， 许 多 对 象 将 被 创建 和 丢弃 的 。 
单 例 的 根 资源 类 的 实例 可 以 通过 一 个 应 用 实例 声明 。 
使 用 Jersey 特定 注释 让 Jersey 支持 两 个 进一步 的 生命 周期 。 


Table 3.1. 资源 域 


域 


Request 
scope 


Per- 
lookup 
scope 


Singleton 


注解 


@RequestScoped 
(or none) 


@PerLookup 


@Singleton 


org.glassfish.jersey.process.internal.RequestScoped 


org.glassfish.hk2.api.PerLookup 


javax.inject.Singleton 
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3.5. Rules of Injection 六 入 规则 


前 面 的 章节 中 已 经 给 出 注释 类 型 的 例子 ， 主 要 用 标注 方法 参数 ， 也 可 以 通过 对 类 的 域 进 行 注 
解 将 值 注入 到 这 些 类 型 。 


本 节 介 绍 了 在 注释 类 型 上 注入 值 的 规则 。 pond n 性 ， 构 造 函 数 参 数 ， 资 源 / 子 资源 / 子 
资源 定位 方法 的 参数 和 bean setter 方 法 。 以 下 介绍 的 这 些 注 入 的 情况 下 : 


Example 3.23. 注入 


@Path("{id:\\d+}") 

public class InjectedResource { 
// 注入 到 属性 
@DefaultValue("q") @QueryParam("p") 
private String p; 


// 注入 到 构造 函数 参数 
public InjectedResource(@PathParam("id") int id) { ... } 


// 注入 到 资源 参数 
@GET 
public String get(@Context Urilnfo ui) { ... } 


// 注入 子 资 源 方法 参数 

QPath("sub-id") 

QGET 

public String get(@PathParam("sub-id") String id) { ... } 


// 注入 子 资 源 方法 参数 定位 器 方法 参数 
@Path("sub-id") 
public SubResource getSubResource(@PathParam("sub-id") String id) { ... } 


// 注入 bean setter 方法 


@HeaderParam("X-header" ) 


public void setHeader(String header) { ... } 


有 一 些 限制 ， 当 注射 到 一 个 生命 周期 为 单 域 的 资源 类 。 在 这 种 情况 下 ， 类 的 属性 或 构造 函数 
的 参数 不 能 被 注入 请 求 特定 的 参数 。 所 以 ， 例 如 ， 以 下 是 不 允许 的 。 


Example 3.24. 错误 | 注入 单 域 


@Path("resource" 
@Singleton 
public static class MySingletonResource { 


@QueryParam("query") 
String param; // 错 误 : 不 能 将 特定 参数 注入 单 例 资 源 ， 
// 会 使 程序 初始 化 失败 


@GET 
public String get() { 
return "query param: " + param; 


上 面 的 例子 验证 了 应 用 程序 不 能 为 单 资源 注入 请 求 特定 的 参数 ， 否 则 验证 失败 的 。 同 样 的 例 
子 ， 如 果 查 询 的 参数 将 被 注入 到 一 个 单 例 构 造 函 数 参 数 则 失败 。 换 名 话说， 如 果 你 希望 一 个 
资源 实例 的 服务 很 多 请 求 ， 则 资源 实例 不 能 绑 定 到 一 个 特定 的 请 求 参数 。 


存在 例外 ， 特 定 请 求 对 象 可 以 注入 到 构造 函数 或 类 属性 。 这 些 对 象 的 运行 时 WA 以 
同时 服务 多 个 请 求 。 这 些 请 求 的 对 象 是 HttpHeaders, Request, Urilnfo, SecurityContex。 这 些 
代理 可 以 使 用 @Context 注释 进行 注入 。 下 面 的 示例 展示 将 代理 注入 单 资 源 类 。 


Example 3.25. Injection of proxies into singleton 


@Path("resource" 
@Singleton 
public static class MySingletonResource { 
@Context 
Request request; // 这 个 是 允许 的 : 
// 请 求 的 代理 将 会 被 注入 进 单 例 


public MySingletonResource(@Context SecurityContext securityContext) { 
/ 这 个 也 是 允许 的 : 
// SecurityContext 的 代理 将 会 被 注入 进 单 例 


@GET 
public String get() { 
return "query param: " + param; 


总 结 ,可 以 为 以 下 结构 注入 : 


Java 构造 
Class fields 
Constructor 
parameters 


Resource 
methods 


Sub 
resource 
locators 


Setter 
methods 


首 述 


将 值 直接 注入 类 属性 。 这 属性 可 以 是 private 但 一 定 不 能 是 final 。 除 了 上 
面 提 到 的 代理 类 型 方法 外 ， 不 能 用 在 单 例 范围 。 


构造 函数 会 调用 注入 值 。 如 果 多 个 构造 函数 其 中 存在 一 个 最 可 注 的 射 参 数 
则 将 被 调用 。 除 了 上 面 提 到 的 代理 类 型 方法 外 ， 不 能 用 在 单 例 范 围 。 


资源 的 方法 ( 带 有 @GET @POST, ... 注 解 ) 包含 的 参数 可 以 在 执行 时 注 
射 。 可 以 在 任何 范围 使 用 。 


子 资源 的 方法 〈 带 有 @GET @POST, ... 注 解 ) 包含 的 参数 可 以 在 执行 时 
注射 。 可 以 在 任何 范围 使 用 。 


值 可 以 被 注入 setter 方法 将 初始 化 属 性 ， 而 不 是 直接 将 值 注 入 属性 的 。 

射 只 能 用 于 @Context 注释 。 这 意味 着 它 不 能 使 用 ， 例 如 将 ERAR 

入 ， 但 可 以 用 在 请 求 注入 。setter 方法 将 会 在 对 象 创建 后 执行 ， 且 只 有 一 

onc ae ES E 全 了 上 面 提 到 的 代理 类 型 ， 
能 在 单 例 范围 内 使 用 。 


下 面 的 示例 显示 所 有 可 能 的 值 可 以 被 注入 的 Java 构建 函数 。 


Example 3.26. 可 能 


注入 的 例子 


@Path("resource" 

public static class SummaryOfInjectionsResource { 
@QueryParam("query") 
String param; // injection into a class field 注入 类 的 属性 


@GET 

public String get(@QueryParam("query") String methodQueryParam) { 
// injection into a resource method parameter 注入 资源 的 方法 参数 
return "query param: " + param; 


@Path("sub-resource-locator") 
public Class<SubResource> subResourceLocator(QQueryParam("query") String subResour 
ceQueryParam) { 


// injection into a sub resource locator parameter 注 入 子 资源 定位 器 参数 
return SubResource.class; 


public SummaryOfInjectionsResource(@QueryParam("query") String constructorQueryPar 


am) { 


// injection into a constructor parameter 注 入 构造 器 的 参数 


@Context 

public void setRequest(Request request) { 
// injection into a setter method 注 入 Setter 方 法 
System.out.println(request != null); 


public static class SubResource { 
@GET 
public String get() { 
return "sub resource"; 


@FormParam 注释 是 特别 的 ， 仅 可 利用 资源 和 子 资 源 的 方法 。 这 是 因为 它 从 请 求实 体 中 提取 


3.6. Use of @Context 使 用 @Context 


前 一 部 分 介绍 @Context 的 使 用 。 第 5 章 描述 了 JAX-RS 的 所 有 标准 的 JAX-RS Java 类 型 ， 可 
以 使 用 Context» 3 JAX-RS 应 用 程序 使 用 servlet ,那么 ServletConfig ` ServletContext 
` HttpServletRequest 和 HttpServletResponse， 是 可 用 @Context ° 


3.7. Programmatic resource model 可 编程 
的 资源 模型 


资源 可 以 由 类 或 实例 也 可 以 由 可 编程 的 资源 模型 构造 。 每 一 个 资源 从 资源 类 创建 也 可 以 使 用 
编程 API 构 建 资 源 生 成 器 。 更 多 信息 请 参考 资源 生成 器 部 分 。 


Chapter 4. Application Deployment and 
Runtime Environments 应 用 部 署 和 运行 时 环 
境 


4.1. Introduction 介绍 


本 章 是 各 种 服务 器 端 环 境 目 前 能 够 在 Jersey 服务 器 运行 的 JAX-RS 应 用 的 概述 。Jersey 支持 
广泛 服务 器 环境 包括 从 轻 量 级 http 容器 到 成 熟 的 Java EE 服务 。Jersey 的 应 用 程序 也 可 以 运行 
在 一 个 OSGI 运行 时 。 如 何在 发 布 应 用 程序 取决 于 应 用 将 运行 在 一 个 Java SE 环境 或 容器 中 的 
方法 。 应 用 的 发 布 取决 于 应 用 是 跑 在 Java SE 环境 还 是 内 诅 的 容器 。 


注意 : 本 章 的 重点 是 服务 器 端的 Jersey 部 署 模型 。 Jersey 客户 端 运行 时 不 需要 特别 的 容器 
环境 ， 运 行 在 普通 Java SE 6 或 更 高 版 本 的 运行 时 即 可 。 


4.2. JAX-RS Application Model 应 用 模型 


JAX-RS 提供 部 署 无 关 的 抽象 类 的 Application 用 来 声明 根 资源 和 提供 类 和 根 资源 ， 以 及 提供 
单 例 。Web 服务 可 以 扩展 这 个 类 声明 的 根 资源 提供 程序 类 。 例 如 ， 


Example 4.1. 部 署 无 关 的 抽象 类 的 应 用 模型 


public class MyApplication extends Application { 
@Override 
public Set<Class<?>> getClasses() { 
Set<Class<?>> s = new HashSet<Class<?>>(); 
s.add(HelloworldResource.class); 
return s; 


或 者 可 以 重用 ResourceConfig - Jersey 自己 实现 的 Application 类 。 这 个 类 可 以 直接 被 实例 
化 ， 然 后 配置 或 可 扩展 和 配置 代码 放置 到 扩展 类 的 构造 函数 。 该 方法 通常 取决 于 所 选 的 部 署 
运行 时 。 


与 Application 相 比 ，ResourceConfig 提供 了 先进 的 功能 来 简化 JAX-RS 组 件 注 册 ， 如 扫描 
根 资源 、 类 提供 者 提供 的 路 径 或 一 组 包 名 的 集合 。 所 有 JAX-RS 组 件 类 都 会 手动 注册 或 者 扫 
描 期 间 找 到 的 类 都 会 自动 添加 到 getClasses 所 返回 的 类 的 集合 中 。 例 如 ， 下 面 的 application 
类 继承 自 ResourceConfig 在 部 署 时 会 扫描 包 org.foo.rest 和 org.bar.rest 中 的 JAX-RS 组 

T : 


Example 4.2. 在 应 用 模型 中 重用 Jersey 的 实现 


public class MyApplication extends ResourceConfig { 
public MyApplication() { 
packages("org.foo.rest;org.bar.rest"); 


} 


4.3. Auto-Discoverable Features 目 动 发 现 
Aw 

功能 

默认 情况 下 Jersey 2.x 不 隐 式 注册 在 classpath 上 可 用 的 模块 中 的 任何 扩展 功能 ， 除 非 明确 在 

扩展 文档 中 进行 说 明 。 用 户 将 明确 注册 的 扩展 功能 来 使 用 他 们 的 Application 子 类 。 一 小 部 分 

Jersey 提供 模块 不 需要 显 式 注册 他 们 的 扩展 功能 ， 因 为 这 些 在 配置 (客户 端 /服务 器 ) 中 将 会 


被 Jersey TH ms 注册 ， 这 些 功 能 模块 实现 的 这 些 特性 将 呈现 在 JAX-RS 应 用 部 署 的 
classpath 上 。 这 些 自动 发 现 模块 包括 : 


e 来 自 jersey-media-moxy 的 JSON 绑 定 特性 
e jersey-media-json-processing 
e jersey-bean-validation 


这 些 模块 也 有 几 个 特性 /提供 者 出 现在 jersey-server 模块 ， 被 过 这 一 机 制 发 现 并 且 受 到 
Mi 自动 发 现 的 配置 的 影响 ( 见 第 4.3.1 节 ，“ 配 置 自动 发 现 机 制 ") ， 即 : 


e WadiFeature - 支持 wadl 处 理 。 
e UriConnegFilter - 在 基于 URI 内 容 协商 的 过 滤器 。 


几乎 所 有 的 Jersey 自动 发 现 的 实现 拥有 AutoDiscoverable.DEFAULT_PRIORITY @Priority 


的 设置 。 


注意 : 自动 发 现 功 能 是 通过 实现 内 部 AutoDiscoverable Jersey SPI 这 个 接口 目前 是 不 公开 
的 ， 以 及 考虑 到 未 来 的 变化 ， 当 试图 使 用 它 要 小 心 。 


4.3.1. Configuring Feature Auto-discovery 
Mechanism 配置 自动 发 现 机 制 
在 Jersey， 以 上 所 描述 的 自动 发 现 机 制 特 性 是 默认 启用 的 。 它 可 以 通过 使 用 特殊 (普通 /服务 
器 /客户 端 ) 属性 来 关闭 : 常见 自动 发 现 属性 

e CommonProperties.FEATURE AUTO DISCOVERY DISABLE 
当 设置 时 ， 自 动 发 现 机 制 在 客户 端 /服务 端 全 局 的 被 关闭 

e CommonProperties.JSON PROCESSING FEATURE DISABLE 
当 设 置 ， 禁 用 JSON 处 理 配 置 (JSR-353) 特征 。 

e CommonProperties.MOXY JSON FEATURE DISABLE 


当 设置 ， 禁 用 MOXy Json 配置 特征 。 


为 每 个 这 些 属性 ,有 一 个 客户 机 /服务 器 计数 器 部 分 分 别 只 在 Jersey 客户 端 或 服务 器 运行 时 叶 
现 ( 见 ClientProperties / ServerProperties)。 设 置 时 ,每 一 个 客户 机 /服务 器 相关 的 特定 自动 发 现 
性 覆盖 相关 的 公共 属性 值 。 


iy 


注意 : 如 果 一 个 自动 发 现 机 制 (一 般 或 特定 功能 ) 被 禁用 ， 然 后 所 有 的 功能 ， 组 件 和 /或 性 
能 ， 采 用 自动 发 现 机 制 的 默认 注册 必须 手动 注册 。 


4.4. Configuring the Classpath Scanning 
配置 Classpath 扫描 


Jersey 使 用 一 个 公共 Java 服务 提供 者 获得 所 有 服务 实现 机 制 。 这 意味 着 Jersey 扫描 整个 类 
路 径 找 到 适当 的 META-INF/services/files ° classpath 中 越 多 的 jar 或 者 war 扫 描 可 能 会 耗费 
更 多 时 间 。 在 使 用 中 ,您 需要 保存 应 用 程序 引导 每 一 毫秒 的 时 间 , 通 常 可 以 禁用 在 Jersey 查找 
服务 提供 者 。 


Jersey 验证 的 SPls 列表 


e AutoDiscoverable (server, client) - 如 果林 用 加 载 服务 ， 则 AutoDiscoverable 特性 自动 禁 
用 

e ForcedAutoDiscoverable (server, client) - Jersey 看 起 来 总 是 加 载 这 些 自动 发 现 功能 即使 
服务 是 禁用 的 

e HeaderDelegateProvider (server, client) 

e ComponentProvider (server) 

e ContainerProvider (server) 

e AsyncContextDelegateProvider (server/Servlet) 


附加 的 Jersey 验证 的 SPIs 列表 ， 以 防 metainf-services 模块 在 classpath 中 


e MessageBodyReader (server, client) 
e MessageBodyWriter (server, client) 
e ExceptionMapper (server, client) 


为 可 以 配置 所 有 SPI 实 现 类 或 子 类 实例 手动 在 您 的 应 用 程序 ,禁用 服务 在 Jersey 并 不 影响 任 
何 Jersey 核心 模块 和 扩展 的 功能 ,可 以 节省 许多 在 应 用 程序 初始 化 期 间 ,以 换取 更 详细 的 应 用 
程序 配置 代码 o 


服务 查找 在 Jersey( 默 认 启 用 ) 可 以 通过 一 个 
CommonProperties. METAINF SERVICES LOOKUP DISABLE 属性 来 禁用 。 有 一 个 客户 端 / 
服务 器 计数 器 部 分 ,只 有 客户 端 或 服务 器 上 禁用 该 特性 分 别 

A :ClientProperties. METAINF_SERVICES_LOOKUP_DISABLE/ServerProperties. METAINF 
SERVICES LOOKUP DISABLE。 在 所 有 其 他 情况 下 ， 客 户 端 /服务 器 特殊 属性 将 会 被 所 关 
联 的 共同 属性 所 徐 盖 ， 当 设置 的 时 候 。 


例如 ， 下 面 的 代码 片断 禁用 服务 提供 者 查找 和 手动 注册 的 实现 不 同 的 JAX-RS 和 Jersey 提供 
的 类 型 (ContainerRequestFilter, Feature, ComponentProvider 和 ContainerProvider) 


Example 4.3. 通过 ResourceConfig 注册 SPI 实现 


ResourceConfig resourceConfig = new ResourceConfig(MyResource.class); 
resourceConfig.register(org.glassfish.jersey.server.filter.UriConnegFilter.class); 
resourceConfig.register(org.glassfish.jersey.server.validation.ValidationFeature.class 
); 
resourceConfig.register(org.glassfish.jersey.server.spring.SpringComponentProvider.cla 
ss); 
resourceConfig.register(org.glassfish.jersey.grizzly2.httpserver.GrizzlyHttpContainerP 
rovider.class); 
resourceConfig.property(ServerProperties.METAINF SERVICES LOOKUP DISABLE, true); 


同样 ， 在 场景 中 的 部 署 模型 需要 扩展 应 用 程序 的 子 类 (如 在 所 有 的 servlet 容 器 部 署 ) ， 可 以 
使 用 下 面 的 代码 来 实现 相同 的 应 用 程序 配置 : 


public class MyApplication extends ResourceConfig { 
public MyApplication() { 

register(org.glassfish.jersey.server.filter.UriConnegFilter.class); 
register(org.glassfish.jersey.server.validation.ValidationFeature.class); 
register(org.glassfish.jersey.server.spring.SpringComponentProvider.class); 
register(org.glassfish.jersey.grizzly2.httpserver.GrizzlyHttpContainerProvider 

.class); 
property(ServerProperties.METAINF SERVICES LOOKUP DISABLE, true); 


4.5. Java SE Deployment Environments 部 
署 在 Java SE 环境 


4.5.1. HTTP JRA 


T Java 的 HTTP 服务 器 展现 了 一 种 简约 、 灵 活 的 部 署 Jersey 应 用 程序 的 方式 * HTTP 服 
器 通常 是 艇 入 在 应 用 程序 中 ， 并 通过 配置 ,以 编程 形式 来 启动 。 一 般 来 说 ,Jersey 容器 为 特定 
HTTP 服务 器 提供 了 一 个 定制 化 的 工厂 方法 ， 用 来 返 回 一 个 正确 初始 化 的 HTTP 服务 器 实 
例 o 


ps 


4.5.1.1. JDK Http Server 


从 Java SE 6 开始 ,Java 运行 时 附带 一 个 内 置 的 轻 量 级 的 HTTP. 服务 器 。Jersey 通过 jersey- 
container-jdk-http 容器 扩展 模块 ， 提 供 集成 这 个 Java SE HTTP. 服务 器 。 此 时 ， 不 是 直接 创 
建 HttpServer 实例 ,而 是 使 用 JdkHttpServerFactory 的 createHttpServer() 方 法 , 它 根据 Jersey 
容器 配置 和 Application 子 类 提供 的 初始 化 来 创建 HttpServer 实例 o 


创建 一 个 AK Jersey 的 jdk http server 非常 简单 : 


Example 4.5. 使 用 Jersey 和 JDK HTTP Server 


URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build(); 
ResourceConfig config = new ResourceConfig(MyResource.class); 
HttpServer server - JdkHttpServerFactory.createHttpServer(baseUri, config); 


JDK HTTP 容器 依赖 : 


<dependency> 
«groupId»org.glassfish.jersey.containers«/groupId» 
<artifactId>jersey-container -jdk-http</artifactId> 
<version>2.21</version> 

</dependency> 


4.5.1.2. Grizzly HTTP Server 


Grizzly 是 一 个 建立 在 Java NIO 之 上 的 支持 多 协议 的 框架 。Grizzly 旨 在 简化 强大 的 和 可 扩展 

nee 务 器 开发 。Jersey 提供 了 一 个 容器 的 扩展 模块 ， 可 以 使 用 Grizzly 作为 运行 JAX-RS 应 
普通 的 HTTP 容器 支持 。 从 Grizzly 服务 器 运行 JAX-RS 或 Jersey 的 应 用 是 一 种 最 轻 量 和 
最 容 多 的 方法 ， 用 来 展现 RESTful 服务 


Grizzly 容器 支持 HTTP 注射 Grizzly 的 特性 org.glassfish.grizzly.http.server.Request 和 
org.glassfish.grizzly.http.server.Response 实例 到 JAX-RS 和 Jersey 应 用 资源 和 供应 者 。 然 
而 ， 由 于 Grizzly 的 Request 是 非 代理 性 的 ，Grizzly Request 的 注入 到 单 例 (RU) 的 JAX- 
RS /和 Jersey 提供 者 只 可 能 通过 javax.inject.Provider 实例 。 (Grizzly Response 会 遭受 同样 


的 限制 。) 


Example 4.6. 使 用 Jersey 和 Grizzly HTTP Server 


URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build(); 
ResourceConfig config = new ResourceConfig(MyResource.class); 
HttpServer server = GrizzlyHttpServerFactory.createHttpServer(uri, config); 


容器 扩展 模块 依赖 要 加 入 : 


<dependency> 
<groupId>org.glassfish.jersey.containers</groupId> 
<artifactId>jersey-container-grizzly2-http</artifactId> 
<version>2.21</version> 

</dependency> 


注意 : 通过 测试 框架 Jersey 使 用 Grizzly 已 经 广泛 的 在 项 目 单元 和 端 到 端 进行 了 测试 。 


4.5.1.3. Simple 服务 器 


Simple 是 一 个 框架 允许 开发 者 创建 HTTP 服务 器 ， 并 嵌入 到 应 用 中 。 同 样 的 ， 通 过 从 jersey- 
container-simple-http 容器 扩展 模块 调用 工厂 方法 实现 创建 服务 器 实例 。 


Simple 的 框架 支持 HTTP 容器 注入 Simple 框架 特性 的 org.simpleframework.http.Request 和 
org.simpleframework.http.Response 实例 到 JAX-RS 和 Jersey 应 用 资源 和 供应 者 。 


Example 4.7. 使 用 Jersey 和 Simple 框架 


URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build(); 
ResourceConfig config = new ResourceConfig(MyResource.class); 
SimpleContainer server = SimpleContainerFactory.create(baseUri, config); 


容器 扩展 模块 依赖 要 加 入 : 


<dependency> 
<groupId>org.glassfish.jersey.containers</groupId> 
<artifactId>jersey-container-simple-http</artifactId> 
<version>2.21</version> 

</dependency> 


注意 : Simple HTTP 容器 不 支持 部 署 在 除了 根 路 径 是 (%] 以 外 的 上 下 文 路 径 。 非 根 路 径 的 上 
下 文 路 径 在 部 署 中 是 被 忽略 的 。 


4.5.1.4. Jetty HTTP Server 


Jetty 是 流行 的 Servlet 容器 和 HTTP 服务 器 。 在 此 我 们 不 深究 Jetty 作为 Servlet 容器 的 能 
(尽管 我 们 在 我 们 的 测试 和 实例 使 用 它 ) ， 因 为 作为 基于 Servlet 部 署 模型 并 没有 什么 特别 ， 
具体 会 在 第 4.7 节 ，“ 基 于 Servlet 部 署 "部 分 进行 描述 。 我 们 将 在 这 里 只 重点 描述 如 何 使 用 
Jetty 的 HTTP 服务 器 。 


Jetty HTTP 容器 支持 注入 Jetty 特性 的 org.eclipse.jetty.server.Request 和 
org.eclipse.jetty.server.Response 实例 到 JAX-RS 和 Jersey 应 用 资源 和 供应 者 。 然 而 ， 由 于 
Jetty HTTP Request 是 非 代理 性 的 ，Jetty Request 的 注入 到 单 例 (默认 ) 的 JAX-RS /和 
Jersey 提供 者 只 可 能 通过 javax.inject.Provider 实例 。 (Jetty Response 会 遭受 同样 的 限 


v] e) 


Example 4.8. 使 用 Jersey 和 Jetty HTTP Server 


URI baseUri - UriBuilder.fromUri("http://localhost/").port(9998).build(); 
ResourceConfig config - new ResourceConfig(MyResource.class); 
Server server - JettyHttpContainerFactory.createServer(baseUri, config); 


容器 扩展 模块 依赖 要 加 入 ( 译 者 注 : 原文 中 依赖 包 有 误 ， 这 里 做 了 更 正 ) : 


<dependency> 
«groupId»org.glassfish.jersey.containers«/groupId» 
«artifactId»jersey-container-jetty-http«/artifactId» 
<version>2.21</version> 

</dependency> 


注意 : Jetty HTTP 容器 不 支持 部 署 在 除了 根 路 径 是 ("1") 以 外 的 上 下 文 路 径 。 非 根 路 径 的 上 下 
文 路 径 在 部 署 中 是 被 忽略 的 。 


4.6. Creating programmatic JAX-RS 
endpoint 创建 可 编程 的 JAX-RS 端点 


JAX-RS 规范 定义 了 可 以 编程 创建 一 个 JAX-RS 应 用 端点 (PRZ) 给 任何 Application 子 类 
的 实例 的 能 力 。 举 例 ，Jersey 支持 Grizzly HttpHandler 实例 的 创建 ， 如 下 : 


HttpHandler endpoint = RuntimeDelegate.getInstance() 
.createEndpoint(new MyApplication(), HttpHandler.class); 


一 旦 Grizzly HttpHandler 端点 创建 时 ， 它 可 用 于 进程 内 部 署 到 一 个 特定 的 URL 。 


4.7. Servlet-based Deployment 基于 Servlet 
A) SRA 


在 一 个 Servlet 容器 ，JAX-RS 定义 了 多 个 部 署 选项 ， 针 对 不 同 的 Servlet 容器 所 支持 Servlet 
文 此 


API 的 版 本 。 下 面 的 部 全 详细 描述 了 这 些 选项 


4.7.1. Servlet 2.x Container 


Jersey 集成 ied 容器 支持 至 少 Serviet 2.5 规范 。 运 行 在 Servlet API 3.0 或 者 更 高 版 本 的 
aca 会 带 给 你 运行 更 多 的 功能 特性 (特别 是 异步 请 求 处 理 支 持 ) 和 更 方便 、 更 灵活 的 部 署 
选项 。 在 这 节 容 ， 我 们 注意 力 集中 在 基本 部 署 模型 Servlet 2.5 或 之 上 版 本 的 容器 


在 Servlet 2.5 环境 ， 你 要 明确 声明 Jersey 容器 Servlet 在 你 的 Web 应 用 的 web.xml 部 署 描 
述 符 文件 中 。 


Example 4.9. 将 Jersey 当做 Servlet 


<web-app> 
<servlet> 
<servlet -name>MyApplication</servlet-name> 
<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class> 
<init-param> 


</init -param> 

</servlet> 

<servlet -mapping> 
<servlet -name>MyApplication</servlet -name> 
<url-pattern>/myApp/*</url-pattern> 


</servlet -mapping> 


</web -app> 


或 者 ， 你 可 以 注册 Jersey 容器 过 滤器 


Example 4.10. 将 Jersey 当做 Servlet Filter 


<web-app> 
<filter> 
<filter -name>MyApplication</filter-name> 
<filter-class>org.glassfish.jersey.servlet.ServletContainer</filter-class> 
<init-param> 


</init -param> 
</filter> 


<filter -mapping> 
<filter -name>MyApplication</filter-name> 
<url-pattern>/myApp/*</url-pattern> 
«/filter-mapping» 


«/web-app» 
«init-param 元 素 内容 将 取决 于 你 如 何 决定 资源 配置 不 同 的 Jersey 资源 。 


4.7.1.1. 自 定 义 Application 子 类 


如 果 你 的 继承 Application 类 来 提供 有 关 根 资源 类 的 列表 (getresources()) 和 单身 

(getsingletons()) ， 即 你 的 JAX-RS 应 用 模型 ， 然 后 你 需要 注册 一 个 
javax.ws.rs.Application [原名 ] 名 称 的 Servlet 或 Servlet 过 滤器 作为 web 应 用 程序 的 初始 化 参 
数 ， 在 web.xml 中 进行 部 署 描述 : 


ii 


Example 4.11. 配置 Jersey && Servlet 或 者 过 滤器 来 自 定义 Application 子 类 


<init -param> 
<param-name>javax.ws.rs.Application</param-name> 
<param-value>org.foo.MyApplication</param-value> 
«/init-param» 


Jersey 将 考虑 所 有 Application 实现 的 getClasses() 和 getSingletons() 方法 的 返回 。 
注意 : JAX-RS 规范 定义 的 配置 名 称 确实 是 javax.ws.rs.Application 和 不 是 
javax.ws.rs.core.Application 可 想 而 知 。 


4.7.1.2. Jersey 扫描 包 


如 果 配 置 属性 无 需 设 置 ， 要 部 署 应 用 程序 只 包括 存储 在 特定 的 包 的 资源 和 提供 者 ， 那 么 你 可 
以 指示 Jersey 自动 扫描 这 些 包 ， 这 样 就 能 自动 注册 找到 的 任何 资源 和 提供 者 : 


Example 4.12. 配置 Jersey 的 Servlet 或 者 Filter 来 扫描 包 


<init -param> 
<param-name>jersey.config.server.provider .packages</param-name> 
<param-value> 

org.foo.myresources, org.bar.otherresources 
</param-value> 

«/init-param» 

«init-param» 
«param-name»jersey.config.server.provider.scanning.recursive«c/param-name» 
<param-value>false</param-value> 

«/init-param» 


Jersey 将 会 自动 发 现 被 选中 的 资源 和 提供 者 。 你 可 以 通过 设置 
jersey.config.server.provider.scanning.recursive 属性 来 决定 Jersey 是 否 扫描 子 包 。 默 认 值 是 
true , 即 忆 用 递归 扫描 子 包 。 


4.7.1.3. 选择 具体 的 资源 和 提供 者 类 


上 述 包 扫描 是 开发 和 测试 是 非常 有 用 ， 而 在 生产 部 署 环境 中 ， 你 可 能 想 要 有 更 多 一 点 的 控制 
枚 举 特定 资源 和 提供 者 类 。 在 Jersey 就 有 可 能 达到 甚至 不 需要 实现 一 个 自 定 义 Application 
子 类 。 特 定 的 资源 和 提供 者 的 完全 限定 类 名 可 以 是 一 个 去 号 分 隔 的 


jersey.config.server.provider.classnames 初始 化 参数 提供 的 值 。 


Example 4.13. 配置 Jersey 的 Servlet 或 者 Filter 来 使 用 类 的 列表 


<init -param> 
<param-name>jersey.config.server.provider .classnames</param-name> 
<param-value> 
org.foo.myresources.MyDogResource, 
org.bar.otherresources.MyCatResource 
</param-value> 
«/init-param» 


注意 : 所 有 已 在 本 部 分 也 适用 于 支持 Servlet API 3 和 以 后 的 技术 规范 Servlet 容器 。 新 的 
Servlet 规范 只 给 你 额外 的 功能 ， 以 及 更 灵活 的 部 署 选 项 。 


4.7.2. Serviet 3.x Container 


4.7.2.1. 无 描述 的 部 署 


一 个 实现 了 Application 子 类 的 JAX-RS 应 用 在 Servlet 3.0 容器 中 将 会 有 很 多 部 署 选 项 。 对 于 
简单 的 部 署 ，web.xml 不 是 必须 的 。 相 反 ， 一 个 @ApplicationPath 注释 可 用 于 自 定 义 
Application 子 类 和 给 给 所 有 配置 中 的 JAX-RS 资源 定义 基础 应 用 程序 URI : 


Example 4.14. 在 JAX-RS 应 用 部 署 中 使 用 @ApplicationPath 和 Servlet 3.0 


@ApplicationPath("resources" ) 
public class MyApplication extends ResourceConfig { 
public MyApplication() { 
packages("org.foo.rest;org.bar.rest"); 


} 


注意 : 在 ResourceConfig 很 多 其 他 的 便利 方法 可 用 于 您 的 自 定 义 类 的 构造 函数 来 配置 您 的 
JAX-RS 应 用 ， 详 见 ResourceConfig API 文 档 。 


如 果 你 不 为 你 的 基于 Maven 的 Web 应 用 项 目 提供 的 web.xml 部 署 描述 文件 ， 你 需要 配置 你 
的 maven-war-plugin 插件 来 忽略 缺失 的 web.xml 文件 ， 通 过 设置 failOnMissingWebXml Az 
置 属 性 为 false 在 你 的 项 目的 pom.xml 文件 中 : 


Example 4.15. 配置 你 的 maven-war-plugin 插件 来 忽略 缺失 的 web.xml 


<plugins> 


<plugin> 
<groupId>org.apache.maven. plugins</groupId> 
<artifactId>maven-war -plugin</artifactId> 
<version>2.3</version> 
<configuration> 

«failonMissingWebXml»false«/failOnMissingWebXml- 

</configuration> 

</plugin> 


</plugins> 


4.7.2.2. 通过 web.xml 部 署 


另 一 种 Servlet 3.x 容器 的 部 署 模型 是 在 web.xml 声明 JAX-RS 应 用 细节 。 这 通常 是 适用 于 更 
复杂 的 部 署 ， 例 如 当 安 全 模型 需要 适当 的 定义 或 额外 的 初始 化 参数 被 传递 到 Jersey 的 运行 
时 。JAX-RS 1.1 和 以 后 的 指定 完全 限定 名 称 ， 实 现 Application， 可 用 于 在 web.xml 部 署 描述 
符 一 个 元 素 定义 为 你 的 应 用 的 一 类 。 


Example 4.16. 在 Servlet 3.0 使 用 web.xml 使 用 JAX-RS 应 用 部 署 


<web-app> 
<servlet> 
<servlet-name>org.foo.rest .MyApplication</servlet -name> 
</servlet> 


<servlet -mapping> 
<servlet-name>org.foo.rest .MyApplication</servlet -name> 
<url-pattern>/resources</url-pattern> 

</servlet -mapping> 


</web -app> 


注意 到 ， 是 在 Servlet 描述 中 省 略 了 。 这 是 一 个 正确 的 声明 使 用 详细 描述 了 Servlet 3.0 扩展 
机 制 ， 在 第 4.7.2.3“ Servlet 程序 机 制 ?部 分 。 还 注意 到 ， 在 使 用 的 示例 中 是 定义 基础 资源 的 
URI ° 


提示 : 在 一 个 Servlet 2.x 运行 时 ， 它 会 声明 Jersey 容器 的 Servlet 或 者 Filter 并 且 将 通过 应 用 
程序 的 实现 类 名 称 为 init-param 实体 中 的 一 个 ， 详 见 第 4.7.1，“Servlet 2。x 容 器 ”。 


4.7.2.3. Servlet 插件 机 制 


Servlet 的 框架 插件 机 制 是 Servlet 3 规范 的 一 个 特性 。 它 简化 了 各 种 建立 在 Servlet 框架 的 配 
置 。 web.xml 文件 不 再 是 所 有 的 配置 选项 中 心 点 ， 它 是 可 能 的 模块 化 部 署 描述 符 利 用 所 谓 的 

Web 片段 的 几 个 具体 和 集中 的 web.xml 文件 的 概念 。 一 组 Web 片段 基本 上 建立 了 最 终 的 部 

署 描述 符 。 该 机 构 还 提供 SPI 钧 ， 使 Web 框架 注册 自己 的 Servlet 容器 或 定制 Servlet 容器 

部 署 过 程 中 的 一 些 其 他 的 方式 。 本 节 描 述 如 何 JAX-RS 和 Jersey Servlet 插件 机 制 。 


4.7.2.3.1. 没有 Application 子 类 的 JAX-RS 应 用 


如 果 没 有 Application (或 者 ResourceConfig ) 子 类 的 存在 ，Jersey 会 动态 添加 Jersey 容器 
Servlet 并 且 设 置 它 的 名 称 到 javax.ws.rs.core.Application 。 这 个 应 用 的 路 径 将 会 被 扫描 并 且 
所 有 的 根 资源 类 (@Path 注解 的 类 ) 跟 @Provider 注 解 的 提供 者 一 样 在 应 用 注解 包 中 将 会 包 
自 定 的 注册 进 JAX-RS 应 用 中 。 应 EMEN 已 经 根据 添加 了 javax.ws.rs.core.Application 
Servlet 映射 的 部 署 描述 符 被 打包 


Example 4.17. 没 用 Application 子 类 的 JAX-RS 应 用 的 web.xml 


<web-app version="3.0" 
xmlns="http://java.sun.com/xml/ns/javaee" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 


<!-- Servlet declaration can be omitted in which case 
it would be automatically added by Jersey --> 
<servlet> 


<servlet-name>javax.ws.rs.core.Application</servlet -name> 


</servlet> 


<servlet -mapping> 
<servlet-name>javax.ws.rs.core.Application</servlet -name> 
<url-pattern>/myresources/*</url-pattern> 
</servlet -mapping> 
</web -app> 


~ 


4.7.2.3.2. 自 定 义 Application 子 类 的 JAX-RS 应 用 


= 


当 存 在 一 个 自 定义 的 应 用 程序 类 ， 在 这 种 情况 下 Jersey 的 服务 器 运行 时 行为 取决 于 是 否 有 一 
个 定义 来 处 理应 用 程序 类 的 Servlet。 

如 果 web.xml & 2 f Servlet 定义 ,初始 化 参数 javax.ws.rs.Application 的 值 是 Application + 
类 的 完全 限定 名 称 ，Jersey 无 需 其 他 步骤 。 


如 果 没 有 定义 自 定义 Application 子 类 的 Servlet > #84 Jersey 会 动态 添加 一 个 Application + 
类 的 完全 限定 名 称 的 Servlet。 为 了 定义 添加 的 Servlet 的 映射 ， 你 可 以 用 @ApplicationPath 

来 注解 自 定义 Application 子 类 (Jersey 将 使 用 注释 值 添加 /* 自动 定义 Servlet 映射 ), 或 者 直接 
在 web.xml 指定 Servlet 映射 。 


在 下 面 的 例子 中 ， 我 们 假设 JAX-RS 应 用 程序 使 用 自 定 义 Application 的 子 类 定义 的 命名 为 
org.example.MyApplication ， 那 么 web.xml 文件 可 以 有 以 下 结构 : 


Example 4.18. 


<web-app version="3.0" 
xmlns="http://java.sun.com/xml/ns/javaee" 
xmlins:xsi="http://www.w3.org/2001/XMLSchema-instance"> 


<!-- Servlet declaration can be omitted in which case 
it would be automatically added by Jersey --> 
<servlet> 
<servlet-name>org.example.MyApplication</servlet -name> 
</servlet> 


<!-- Servlet mapping can be omitted in case the Application subclass 
is annotated with @ApplicationPath annotation; in such case 
the mapping would be automatically added by Jersey --> 
<servlet -mapping> 
<servlet-name>org.example.MyApplication</servlet -name> 
<url-pattern>/myresources/*</url-pattern> 
</servlet -mapping> 
</web -app> 


注意 : 如 果 您 的 自 定 义 Application 子 类 打包 成 了 wan 它 定义 了 哪些 资源 将 被 考虑 。 


e 如 果 getClasses() 和 getSingletons() 方法 返回 一 个 空 集 合 ， 然 后 所 有 的 根 资 源 类 和 提供 
者 封装 在 Web 应 用 程序 档案 将 被 使 用 ，Jersey 会 自 mU tdm .war 文件。 

e 如 果 上 述 两 种 方法 getClasses() 和 getSingletons() 返回 一 个 非 空 集合 ， 这 些 类 和 /或 单 例 
会 发 布 在 JAX-RS 应 用 中 。 


Table 4.1. Servlet 3 Pluggability Overview 插件 机 制 总 览 
Condition 

Jersey action 

Servlet Name 

web.xml </tr></thead> 


没有 Application 子 类 添加 Servlet javax.ws.rs.core.Application 需要 Servlet #4t Application 
子 类 被 已 经 存在 的 Servlet 控制 无 action 已 经 定义 不 需要 Application 子 类 没有 被 已 经 存在 的 
Servlet 控制 添加 ServletApplication 子 类 的 全 限定 名 若 没有 @ApplicationPath 注解 在 
Application 子 类 , 则 Servlet 映射 是 必须 的 


4.7.3. Jersey Servlet container modules % 4 7% 
块 


Jersey 使 用 它 自己 的 实现 了 Servlet 的 ServletContainer 和 Filter API 去 整合 Servlet 容器 。 
任何 JAX-RS 运行 时 ，Jersey 提供 对 Servlet 容器 的 支持 使 得 能 够 支持 Servlet 2.5 版 本 以 上 
规范 。 支 持 在 一 个 Servlet 容器 顶层 的 JAX-RS 2.0 FRR > Servlet 规范 版 本 必需 是 3 或 
更 高 版 本 的 支持 。 


当 部 署 进 Servlet 容器 ，Jersey 应 用 一 般 会 打包 成 .war 文件。 与 任何 其 他 Servlet 应 用 程序 
一 样 , JAX-RS 应 用 程序 类 打包 在 WEB-INF/classes 或 者 WEB-INF/lib ， 所 需 的 应 用 程序 库 位 
于 WEB-INF/lib 。 有 关 详 细 信息 ,请 参阅 Servlet 规范 (JSR 315) » 


Jersey 提供 了 两 个 Servlet 模块 。 第 一 个 模块 是 Jersey 核心 Serviet 模块 ,提供 核心 Servlet 
需要 集成 的 支持 ,需要 Servlet 2.5 或 更 高 的 容器 : 


<dependency> 
«groupId»org.glassfish.jersey.containers«/groupId» 
<artifactId>jersey-container-servlet-core</artifactId> 
</dependency> 


为 了 支持 额外 的 Servlet 3.x 部 署 模式 和 异步 JAX-RS 资源 的 编程 模型 ,另外 一 个 Jersey 模块 
为 : 


<dependency> 
«groupId»org.glassfish.jersey.containers«/groupId» 
<artifactId>jersey-container-servlet</artifactId> 
</dependency> 


jersey-container-servlet 模块 取决 于 jersey-container-servlet-core 模块 ,因此 当 使 用 它 时 , 它 不 
需要 显 式 地 声明 jersey-container-servlet-core 依赖 性 。 


注意 ,在 简单 的 情况 下 ,您 不 需要 提供 部 署 描述 ((Web.xml) 而 是 使 用 @ApplicationPath 注释 ,如 
4.7.2.3.1 节 “无 Application 子 类 的 JAX-RS 应 用 "所 述 。 


4.8. Java EE Platform 在 Java EE 平台 


本 节 描 述 ,如 Jersey JAX-RS 资源 的 各 种 Java EE 平台 元 素 。JAX-RS 和 Jersey 给 你 
更 多 选择 的 可 能 性 ,符合 你 的 口味 (和 设计 ), 取 决 您 决定 使 用 Java EE 技术 管理 你 的 资源 。 


4.8.1. Managed Beans 管理 Beans 


Jersey 支持 使 用 Java EE 托管 bean 作为 根 资源 类 、 子 类 提供 者 以 及 Application 子 类 。 


在 下 面 的 代码 中 ,您 可 以 找到 一 个 bean 的 一 个 例子 ,使 用 受 管 bean 拦截 器 定义 为 一 个 JAX- 
RS bean ° bean 用 于 拦截 方法 调用 资源 getlt(): 


@ManagedBean 
QPath("/managedbean") 
public class ManagedBeanResource { 


public static class MyInterceptor { 
QAroundInvoke 
public String around(InvocationContext ctx) throws Exception { 
System.out.println("around() called"); 
return (String) ctx.proceed(); 


} 


@GET 
@Produces("text/plain" ) 
@Interceptors(MyInterceptor.class) 
public String getIt() { 

return "Hi managed bean!"; 


} 


4.8.2. Context and Dependency Injection (CDI) 
上 下 文 和 依赖 注入 

CDI bean 可 以 作为 Jersey 根 资源 类 、 子 类 提供 者 以 及 Application 子 类 。 提 供 者 以 及 
Application 子 类 必 是 单 例 或 应 用 程序 作用 域 。 


下 一 个 例子 显示 了 一 个 使 用 CDI bean 作为 JAX-RS 资源 类 。 我 们 假设 ,CDI 已 经 启用 。 该 例子 
通过 使 用 另 一 个 bean (MyOtherCdiBean) 提 供 类 型 安全 的 依赖 注入 分 开 使 用 CDI : 


@Path("/cdibean" ) 
public class CdiBeanResource { 
@Inject MyOtherCdiBean bean; // CDI injected bean 


@GET 

@Produces("text/plain" ) 

public String getIt() { 
return bean.getIt(); 


} 


4.8.3. Enterprise Java Beans (EJB) 


无 状态 和 单 例会 话 bean 可 以 作为 Jersey 根 资源 类 、 子 类 提供 者 和 /或 Application 子 类 。 你 可 
以 选择 从 EJB 本 地 接口 的 注释 方法 或 直接 的 在 一 个 无 接口 的 EJB POJO 方法 。. JAX-RS 规 
范 要 求 其 实现 者 发 现 EIB 通过 检查 注释 类 (或 本 地 接口 ), 而 不 是 在 部 署 描述 符 (ejb-jarxml) » 
此 ,保持 您 的 JAX-RS 应 用 程序 移植 ,不 覆盖 EIB 注解 或 提供 任何 在 部 署 描述 符 文件 附加 的 元 
数据 。 


以 下 示例 包含 一 个 无 状态 EJB 本 地 接口 用 于 Jersey : 


@Local 

public interface LocalEjb { 
@GET 
@Produces("text/plain" ) 
public String getIt(); 

} 


@Stateless 
@Path("/stateless") 
public class StatelessEjbResource implements LocalEjb { 
@Override 
public String getIt() { 
return "Hi Stateless!"; 


} 


£ S 


请 注意 ,Jersey 目前 不 支持 JAX-RS 应 用 程序 打包 成 单独 的 EJB 模块 的 部 署 (ejb-jars)。 使 用 
EJB 作为 JAX-RS 资源 , EJB 需要 打包 直接 在 WAR 或 EAR 中 包含 至 少 一 个 WAR 。 这 是 确 
tk Servlet 容器 初始 化 ,对 于 Jersey 运行 时 的 引导 是 必要 的 . 


4.8.4. Java EE Servers 在 Java EE 服务 器 中 


4.8.4.1. GlassFish Application Server 


2.3.1 中 解释 说 ,在 GlassFish 中 你 不 需要 添加 任何 特定 的 依赖 ,Jersey 已 经 打包 在 GlassFish 
尔 只 需要 将 provided-scoped 依赖 项 添加 到 您 的 项 目 使 能 够 编译 它 。 在 运行 时 ,GlassFish 
将 确保 您 的 应 用 程序 能 够 访问 Jersey 库 。 


从 2.7 版 本 开始 , Jersey 允许 使 用 @javax.inject.Inject 注入 注解 注入 Jersey 特定 类 型 进 CDI 
来 启用 JAX-RS 组 件 。 这 也 包括 自 定义 HK2 绑 定 ,被 配置 为 Jersey 应 用 程序 Vn 部 分 。 该 功 
能 特别 允许 使 用 Jersey 监测 统计 (统计 特性 ) 提 供 在 CDI 的 环境 中 ,在 注射 是 唯一 获得 监测 数据 的 


意思 。 


raul 


因为 CDI 和 HK2 都 使 用 相同 的 注入 注释 ,Jersey 在 某 些 情况 下 可 以 发 生 歧 义 , 这 可 能 导致 严重 
的 运行 时 的 问题 。 获 得 更 好 的 控制 Jersey 评估 HK2 注 入 ,终端 用 户 可 以 利用 新 引进 的 
Hk2CustomBoundTypesProvidenSPI。 请 参阅 有 关 javadoc 得 到 详细 信息 在 应 用 程序 中 如 何 
使 用 SPI。 


4.8.4.2. Oracle WebLogic Server 


WebLogic 12.1.2 及 早期 版 本 ,只 支持 JAX-RS 1.1 (JSR 311) 的 Jersey 1.x (WebLogic 12.1.2 
附带 Jersey 1.13)。 更 新 Jersey 1.x 的 版 本 在 早 些 时 候 这 些 WebLogic 服务 器 版 本 ,请 参阅 
Updating the Version of Jersey JAX-RS RI 在 WebLogic RESTful Web 服 务 开发 指南 。 


在 WebLogic 12.1.3, 附 带 Jersey 1.18 作为 JAX-RS 1.1 默认 的 提供 者 。 在 这 个 版 本 的 
WebLogic,JAX-RS 2.0 (使 用 Jersey 2.5.1) 为 一 个 支持 可 选 安装 共享 库 。 请 通读 WebLogic 
12.1.3 RESTful Web Services Development Guide, 里 面 详细 说 明了 在 WebLogic 12.1.3 如 何 
启用 JAX-RS 2.0 


4.8.4.3. Other Application Servers 


第 三 方 Java EE 应 用 服务 器 通常 附带 一 个 JAX-RS 实现 。 如 果 您 想 要 使 用 Jersey 而 不 是 默认 
的 JAX-RS 提供 者 ,您 需要 将 J ersey 库 添加 到 您 的 类 路 径 和 禁用 默认 的 JAX-RS 提供 者 的 容 


vea 
zm 


一 般 来 说 ,Jersey 将 被 部 署 为 一 个 Servlet 并 且 资 源 可 以 部 署 在 不 同 的 方式 ,如 本 节 所 述 。 然 而 ， 
确切 的 步骤 将 因 供应 商 不 同 而 不 同 。 


4.9. OSGi 


OSGi 支持 添加 到 Jersey 1.2 版 。 自 那 之 后 ,您 应 该 能 够 使 用 标准 OSGi 意 味 着 球衣 基于 Web 应 
用 程序 运行 在 OSGI 运行 时 中 描述 的 OSGI 服务 平台 企业 规范 。Jersey 目前 兼容 OSGI 4.2.0, 
该 规范 可 以 从 OSGi4.2.0 站 点 下 载 。 


运行 OSGi web 应 用 程序 的 两 种 支撑 方式 有 : 


e WAB (Web Application Bundle) 
e HTTP Service 


WAR 实际 上 只 是 一 个 OSGi 类 型 的 WAR 文件 。HTTP 服 务 特性 允许 您 在 OSGi 运 行 时 中 发 布 
Java EE Servlet 。 


下 面 两 个 例子 被 添加 到 Jersey 分 布 描述 上 述 特点 ,展示 如 何 使 用 Jersey: 


e WAB Example 
e HTTP Service example 


两 个 例子 是 多 模块 maven 项 目 , OSGI 应 用 程序 包含 一 个 模块 和 一 个 测试 模块 。 测 试 是 基于 
PAX Exam ° AA OSGI 的 例子 还 包括 自述 文件 包含 指令 如 何 使 用 Apache Felix 框 架 手动 运行 
示例 应 用 程序 。 


其 余 的 章节 描述 了 如 何 运行 上 述 示 例 在 GlassFish 4 应 用 服务 器 上 。 


4.9.1. Enabling the OSGi shell in Glassfish 在 
Glassfish 使 用 OSGi ^c 


自从 GlassFish 使 用 Apache Felix ,GlassFish 的 OSGi 运 行 时 就 出 现 了 。 然 而 ,出 于 安全 原因 ， 
OSGi shell 被 关闭 。 但 是 您 可 以 显 式 地 启用 它 通过 GlassFish 控制 台 开 始 ,创建 一 个 Java 系 统 
属性 glassfish.osgi.start.level.final 最 后 ,将 它 的 值 设置 为 3: 


Example 4.19. 


局 动 控制 台 : 


~/glassfish/bin$ ./asadmin 
Use "exit" to exit and "help" for online help. 
asadmin> 


检查 java 属性 值 (从 配置 文件 中 加 载 ): 


asadmin> list-jvm-options 


-Dglassfish.osgi.start.level.final-2 


根据 类 型 添加 值 : 


asadmin> create-jvm-options --target server -Dglassfish.osgi.start.level.final=3 


第 二 个 选项 是 修改 Osgi.properties 配置 文件 : 


# Final start level of OSGi framework. This is used by GlassFish launcher code 
# to set the start level of the OSGi framework once server is up and running so that 
# optional services can start. The initial start level of framework is controlled usin 


g 
# the standard framework property called org.osgi.framework.startlevel.beginning 


glassfish.osgi.start.level.final-3 


执行 Felix shell: 


asadmin» osgi lb 
. list of bundles ... 


或 者 启动 shell 使 用 osgi-shell 命令 ( 域 必须 启动 ， 否 则 osgi shell 不 能 启动 ): 


asadmin> osgi-shell 
Use "exit" to exit and "help" for online help. 
gogo$ 


gogo$ lb 
. list of bundles ... 


4.9.2. WAB Example 


如 前 所 述 ,WAR 只 是 一 个 OSGi 类 型 的 WAR 文件 。 除 了 通常 的 OSGi 头 必 须 除 了 含有 一 种 特 
殊 的 头 ,Web-ContextPath, 指 定 web 应 用 程序 的 上 下 文 路 径 。 我 们 的 WAB (在 其 他 旁边 ) 出 现在 
以 下 标题 清单 : 


Web-ContextPath: helloworld 
Webapp-Context: helloworld 
Bundle-ClassPath: WEB-INF/classese 


第 二 个 标题 是 忽视 了 GlassFish ,但 可 能 需要 其 他 容器 不 能 完全 符合 上 面 提 到 的 企业 OSGI 规 
范 。 第 三 个 清单 头 值得 一 提 的 是 捆绑 包 类 路 径 中 指定 在 哪里 可 以 找到 应 用 程序 的 Java 类 包 存 
档 。 可 以 找到 更 多 关于 标题 出 现在 OSGi 在 OSGi Wiki 。 


更 详细 的 信 ， JL WAB Example 示例 源 代 码 。 这 个 例子 没 打包 成 一 个 war 文件 ,而 是 在 构 
建 时 一 个 war fot 外 的 jar 被 产生 出 来 。 看 下 一 个 示例 看 如 何 在 GlassFish 部 署 基 于 
OSGi 的 Jersey 应 用 程序 。 


4.9.3. HTTP Service Example 


注意 当 在 GlassFish 部 署 一 个 OSGi HTTP 服务 的 例子 时 ,请 确保 OSGI HTTP 服务 包 是 安装 
在 您 的 GlassFish 实例 中 。 


你 可 以 直接 安装 和 激活 Jersey 应 用 程序 包 。 在 我 们 的 示例 中 ,您 可 以 安装 示例 包 存 储 在 本 地 
(和 另外 Jersey 源码 构建 ): 


1) 编译 (可 选 ) 


examples$ cd osgi-http-service/bundle 
bundle$ mvn clean package 


也 可 以 从 Java.net Maven Repository 获 取 编 译 好 的 二 进 制 文件 


gogo$ install file:///path/to/file/bundle. jar 
Bundle ID: 303 


nz dk. 


或 直接 从 maven repository 安装 


gogo$ install http://maven.java.net/content/repositories/releases/org/glassfish/jersey 
/examples/osgi-http-service/bundle/<version>/bundle-<version>. jar 
Bundle ID: 303 


确保 «version» 替换 为 适当 的 版 本 号 。 哪 一 个 是 合适 取决 于 特定 的 您 正在 使 用 GlassFish 4. x 
版 本 。 包 的 版 本 不 能 高 于 GlassFish 4.x 中 Jersey 集成 的 版 本 服务 器 。Jersey 包 在 OSGI 级 
别 声 明 其 他 包 的 依赖 关系 ,这 些 依赖 项 版 本 敏感 的 。 如 果 假 设 使 用 例子 包 从 是 2.5 版 本 ,但 是 


Glassfish 中 Jersey 版 本 是 2.3.1, 依 赖 不 会 合适 , 包 不 会 开始 。 如 果 发 生 这 种 情况 ,这 个 错误 将 
是 这 样 的 : 
gogo$ lb 


303 | Installed | 1| jersey-examples-osgi-http-service-bundle (2.5.0.SNAPSHOT ) 
gogo$ start 303 


org.osgi.framework.BundleException: Unresolved constraint in bundle 
org.glassfish.jersey.examples.osgi-http-service.bundle [303]: Unable to resolve 308.0: 
missing requirement 

[303.0] osgi.wiring.package; (&(osgi.wiring.package-org.glassfish.jersey.servlet) 
(version»-2.5.0)(!(version»-3.0.0))) 


gogo$ 


在 相反 的 情况 下 (例如 包 版 本 是 2.3.1 fe Glassfish 中 Jersey 版 本 更 高 ), 一 切 都 应 该 正常 运 # 


R 如 果 你 是 从 主干 源码 编译 GlassFish ae Jersey 发 布 的 示例 ,您 很 可 能 能 够 
运行 从 最 近 的 Jersey 发 布 的 示例 ,作为 球衣 团队 通常 集成 了 所 有 新 发 布 的 在 GlassFish 中 
Jersey hk ° 


最 后 ， 启 动 包 : gogo$ start 303 
再 一 次 , 包 ID( 在 我 们 的 例子 中 303 ) 已 经 被 正确 的 安装 命令 返回 的 。 


该 示例 应 用 程序 现在 应 该 启动 并 运行 。 你 可 以 访问 它 在 http://localhost:8080/osgi/jersey-http- 
service/status。 更 多 细节 请 参阅 HTTP 服务 示例 源 代码 示例 。 


4.10. Other Environments 其 他 环境 


4.10.1. Oracle Java Cloud Service 云 服 务 


Oracle 公共 云 是 基于 WebLogic 服务 器 ,同样 ,在 文章 中 同样 关于 WebLogic 服务 器 部 署 (请 参见 
4.8.4.2 Oracle WebLogic Server)。 更 多 关于 Oracle Java 云 服 务 , 请 看 指南 


Chapter 5. Client API € 7 3% API 


本 章 提 供 了 and sada MÀ 决 速 介绍 。 这 里 描述 的 示例 使 用 轻 量 
级 的 Grizzly HTTP 服 务 器 。 在 本 章 的 最 后 你 将 看 到 如 何 实现 相同 的 功能 的 JavaEE 的 Web 应 用 
程序 ， 该 程序 可 以 部 FEIET 支持 Servlet 2.5 和 更 高 版 本 的 servlet 容器 里 面 。 


译 者 注 : 本 章 所 有 例子 的 源码 ， 可 以 在 https://github.com/waylau/Jersey-2.x-User-Guide- 
Demos 获取 到 。 


本 节 介 绍 了 JAX-RS 客户 端 APl, 这 是 一 个 基于 Java API 流利 沟通 的 RESTful Web 服务 。 这 个 
标准 的 APl, 也 属于 Java EE 7 目的 是 使 它 很 容易 通过 HTTP 协议 消费 Web 服务 ,使 开发 人 员 
能 够 简明 、 高 效 地 实现 移动 客户 端 解决 方案 ,利用 现 有 的 HTTP 连接 器 和 完善 客户 端 实现 


JAX-RS 客户 端 API 可 以 用 来 消费 任何 暴露 的 HTTP. 协议 或 它 的 扩展 (例如 WebDAV), 和 并 不 
局 限于 服务 使 用 JAX-RS 实现 。 然 而 ,熟悉 JAX-RS 应 该 找到 客户 端 API 的 开发 人 员 服 务 的 补 
充 , 特 别 是 如 果 客 户 端 APL 是 利用 这 些 服 务 ,这 些 服 务 或 测试 。JAX-RS ŽP WAPI 专 有 
Jersey.x 客户 机 API 和 开发 人 员 熟 悉 Jersey.x 客户 机 API 应 该 发 现 它 容易 理解 所 有 的 概念 引入 
新 的 JAX-RS 客户 端 API。 


ZP ža API 的 目标 是 3 个 : 
1. 封 装 的 关键 约束 REST 架构 风格 , 即 统一 接口 约束 和 相关 数据 元 素 ,如 客户 端 Java 工件 ; 


2. 使 它 容易 通过 暴露 HTTP 来 消费 RESTful Web 服务 ,一 样 JAX-RS 服务 器 端 API 很 容易 开 
发 RESTful Web 服务 ; 


3. 有 共同 的 概念 和 JAX-RS API 的 扩展 点 之 间 的 服务 器 和 客户 端 编程 模型 。 


作为 标准 JAX-RS 客户 端 API 扩展 ,Jersey 客户 端 API 支持 可 插 拔 的 体系 结构 允许 使 用 不 同 
的 底层 实现 HTTP. 客户 端 连 接 器 。 几 个 这 样 的 实现 目前 都 由 Jersey 提供。 我 们 有 一 个 默认 客 

户 端 连接 器 使 用 Http(S)JURLConnection 提 供 JDK 以 及 连接 器 实现 基于 Apache Http 客 户 机 ,Jetty 
Http 客户 端 和 Grizzly 异步 客户 端 。 


5.1. Uniform Interface Constraint 统一 接口 


约束 


统一 接口 约束 边界 RESTful Web 服务 的 体系 结构 ,以 便 客户 端 ,如 浏览 器 ,可 以 使 用 相同 的 接口 
与 任何 服务 通信 。 这 是 一 个 非常 强大 的 概念 在 软件 工程 中 ,使 基于 网 络 的 搜索 引擎 和 服务 混搭 
式 应 用 成 为 可 能 。 它 导致 属性 如 : 


1. 简 单 ,架构 更 容易 理解 和 维护 ， 


2. 可 演化 性 或 松散 耦合 、 客 户 和 服务 可 以 随时 间 推 移 而 发 展 也 许 是 新 的 、 意 想不到 的 方式 , 同 
时 保持 向 后 兼容 性 。 


需要 进一步 的 约束 : 

1. 每 一 个 由 URI 标识 的 资源 ; 

2. 通 过 HTTP 客户 端 交 互 与 资源 使 用 一 组 固定 的 HTTP 请 求 和 响应 方法 ; 
3. 可 以 返回 定义 一 个 或 多 个 媒体 类 型 的 资源 ; 

4. 内 容 可 以 链接 到 更 多 的 资源 。 


att jl 过 程 重复 一 遍 , 应 应 该 是 熟悉 的 人 都 使 用 一 | EU | 览 器 填写 HTML 表单 和 链接 。 基于 同样 的 过 
程 适 用 于 非 浏 览 器 客户 端 。 


许多 现 有 的 基于 java 的 客户 端 APl, 比 如 Apache HTTP 客户 端 API 或 HttpUrlConnection JDK 
太 专注 于 提供 的 “客户 端 -服务 器 ?约束 的 交往 请 求 和 响应 ,而 不 是 由 URI 标 识 ,使 用 一 组 国定 的 
HTTP 方 法 的 资源 。 

JAX-RS 资 源 的 客户 端 API 是 一 个 Java 类 的 实例 WebTarget。 封 装 了 一 个 URI。 固 定 的 HTTP 
方法 可 以 调用 基于 WebTarget。 表 示 是 Java 类 型 ， 它 的 实例 ， 可 以 包含 链接 ， 可 以 创建 新 实 
例 WebTarget ° 


5.2. Ease of use and reusing JAX-RS artifacts 
易于 使 用 和 可 重用 的 JAX-RS 工件 


因为 JAX-RS 组 件 被 表示 为 一 个 带 注释 的 Java 类 型 , 它 很 容易 配置 ,传递 和 注入 的 方式 在 其 他 
客户 端 api 不 是 很 直观 的 或 可 能 。Jerse y 客 户 端 API 重 用 JAX-RS 和 Jersey 实现 的 许多 方面 
如 : 


1. 使 用 UriBuilder 和 UriTemplate 更 安全 的 构建 URI; 


2. 内 置 支 持 Java 类 型 的 表示 如 byte[], String, Number, Boolean, Character, InputStream, 
java.io.Reader, File, DataSource, JAXB beans 以 及 额外 Jersey 特性 的 JSON 和 Multi Part 
的 支持 。 


3. 使 用 流利 的 构建 式 API 模式 ,让 它 更 容易 构建 请 求 。 


一 些 api ,比如 Apache HTTP 客户 端 或 HttpURLConnection 可 能 相当 难以 使 用 和 /或 需要 太 多 
的 代码 做 一 些 相 对 简单 的 ,尤其 是 当 客 户 需要 了 解 不 同 的 载荷 表示 。 这 就 是 为 什么 Jersey 实现 
JAX-RS Client API 支持 包装 HttpUrlConnection 和 Apache HTTP 客户 端 ? 因此 可 以 获得 既 

定 的 JAX-RS 实现 的 好 处 和 特点 而 变 得 易于 使 用 的 好 处 JAX-RS 客户 端 API 的 简单 的 设计 。 

与 低层 的 HTTP 客 户 端 库 , 例 如 ,发 送 一 个 POST 请 求 与 一 群 类 型 的 HTML 表单 参数 和 接收 响应 

反 序 列 化 到 JAXB bean 却 并 非 易 事 。 用 新 的 JAX-RS 客户 端 API 支持 泽 这 个 任务 非常 简单 


Example 5.1. POST request with form parameters 将 form 参 数 以 POST 形式 请 求 


Client client = ClientBuilder.newClient(); 
WebTarget target = client.target("http://localhost:9998").path("resource"); 


Form form = new Form(); 
form.param("x", "foo"); 
form.param("y", "bar"); 


MyJAXBBean bean = 
target.request (MediaType.APPLICATION_JSON_TYPE) 
.post(Entity.entity(form,MediaType.APPLICATION FORM URLENCODED TYPE), 
MyJAXBBean.class); 


在 5.1 的 例子 中 首先 创建 一 个 新 的 WebTarget 实例 使 用 一 个 新 的 客户 端 实 例 ,接着 创建 一 个 表 
单 实例 有 两 个 参数 形式 。 一 旦 准备 好 了 ,表单 实例 发 布 到 目标 资源 。 首 先 ,在 请 求 中 指定 可 接受 
的 媒体 类 型 (...) 方 法 。 然 后 在 post(...) 方 法 ,调用 一 个 静态 方法 在 JAX-RS 实体 是 由 构造 请 求实 
体 实例 和 附加 适当 的 内 容 媒 体 类 型 的 形式 被 发 送 的 实体 。post(...) 方 法 的 第 二 个 参数 指定 响应 
实体 的 Java 类 型 ,应 该 从 方法 返回 一 个 成 功 的 响应 。 在 这 种 情况 下 请 求 JAXB bean 的 一 个 实例 
返回 成 功 。Jersey 客 户 端 API 负 责 选择 适当 的 MessageBodyWriter < T > 序列 化 表单 的 实例 , 调 
用 POST 请 求 和 响应 消息 有 效 负 载 的 生产 和 反 序 列 化 到 JAXB bean 的 一 个 实例 使 用 一 个 适当 的 
MessageBodyReader < T > ° 


如 果 上 面 的 代码 必须 使 用 HttpUrlConnection 编写 ,开发 人 员 必 须 编 写 自 定 义 代 码 序 列 化 表单 
数据 发 送 POST 请 求 和 响应 输入 流 反 序列 化 成 JAXB bean。 另 外 , 写 更 多 的 代码 必须 使 它 容 易 
重用 相同 的 逻辑 通信 时 资源 “http:/Wlocalhost:8080/resource” ,是 由 JAX-RS 代表 WebTarget 实 
例 在 我 们 的 例子 中 。 


5.2 Ease of use and reusing JAX-RS 
artifacts 多 于 使 用 和 可 重用 的 JAX-RS 工件 


因为 JAX-RS 组 件 被 表示 为 一 个 带 注释 的 Java 类 型 , 它 很 容易 配置 ,传递 和 注入 的 方式 在 其 他 
客户 端 api 不 是 很 直观 的 或 可 能 。Jersey 客户 端 API 重用 JAX-RS 和 Jersey 实现 的 许多 方面 
如 : 


1. 使 用 UriBuilder 和 UriTemplate 更 安全 的 构建 URI; 


置 支持 Java 类 型 的 表示 如 byte[], String, Number, Boolean, Character, InputStream, 
ee File, DataSource, JAXB beans 以 及 额外 Jersey 特性 的 JSON 和 Multi Part 
的 支持 。 


3. 使 用 流利 的 构建 式 API 模式 ,让 它 更 容易 构建 请 求 。 


一 些 api ,比如 Apache HTTP 客户 端 或 HttpURLConnection 可 能 相当 难以 使 用 和 /或 需要 太 多 
的 代码 做 一 些 相 对 简单 的 ,尤其 是 当 客户 需要 了 解 不 同 的 载荷 表示 。 这 就 是 为 什么 Jersey 实现 
JAX-RS Client API 支持 包装 HttpUriConnection fe Apache HTTP 客户 端 。 因 此 可 以 获得 既 
定 的 JAX-RS 实现 的 好 处 和 特点 而 变 得 易于 使 用 的 好 处 JAX-RS 客户 端 API 的 简单 的 设计 。 
与 低层 的 HTTP 客 户 端 库 , 例 如 ,发 送 一 个 POST 请 求 与 一 群 类 型 的 HTML 表单 参数 和 接收 响应 
反 序 列 化 到 JAXB bean 却 并 非 易 事 。 用 新 的 JAX-RS 客户 端 APL 支持 泽 这 个 任务 非常 简单: 


Example 5.1. POST request with form parameters 将 form 参 数 以 POST 形式 请 求 


Client client = ClientBuilder.newClient(); 
WebTarget target = client.target("http://localhost:9998").path("resource"); 


Form form = new Form(); 
form.param("x", "foo"); 
form.param("y", "bar"); 


MyJAXBBean bean - 
target.request(MediaType.APPLICATION JSON TYPE) 
.post(Entity.entity(form,MediaType.APPLICATION FORM URLENCODED TYPE), 
MyJAXBBean.class); 


在 5.1 的 例子 中 首先 创建 一 个 新 的 WebTarget 实例 使 用 一 个 新 的 客户 端 实例 ,接着 创建 一 个 表 

单 实例 有 两 个 参数 形式 。 一 旦 准备 好 了 ,表单 实例 发 布 到 目标 资源 。 首 先 ,在 请 求 中 指定 可 接受 
的 媒体 类 型 (...) 方 法 。 然 后 在 post(...) 方 法 ,调用 一 个 静态 方法 在 JAX-RS 实体 是 由 构造 请 求实 
体 实 例 和 附加 适当 的 内 容 媒 体 类 型 的 形式 被 发 送 的 实体 。post(...) 方 法 的 第 二 个 参数 指定 响应 
实体 的 Java 类 型 ,应 该 从 方法 返回 一 个 成 功 的 响应 。 在 这 种 情况 下 请 求 JAXB bean 的 一 个 实例 


返回 成 功 。Jersey 客 户 端 API 负 责 选择 适当 的 MessageBodyWriter < T > 序列 化 表单 的 实例 , 调 
用 POST 请 求 和 响应 消息 有 效 负 载 的 生产 和 反 序 列 化 到 JAXB bean 的 一 个 实例 使 用 一 个 适当 的 
MessageBodyReader < T > ° 


如 果 上 面 的 代码 必须 使 用 HttpUrlConnection 编写 ,开发 人 员 必须 编写 自 定义 代码 序列 化 表单 
数据 发 送 POST 请 求 和 响应 输入 流 反 序列 化 成 JAXB bean。 另 外 , 写 更 多 的 代码 必须 使 它 容 多 
重用 相同 的 逻辑 通信 时 资源 “http://localhost:8080/resource”, 是 由 JAX-RS 代表 WebTarget 实 
例 在 我 们 的 例子 中 。 


5.3. Overview of the Client API 客户 站 API 


5.3.1. Getting started with the client API 开始 


44% Fl Jersey JAX-RS 客户 端 支持 的 依赖 关系 ， 请 查看 依赖 。 


您 可 能 还 希望 使 用 一 个 自 定 义 连接 器 实现 。 在 这 种 情况 下 ,您 将 需要 包含 额外 的 依赖 模块 包含 
您 想 要 使 用 的 自 定义 客户 端 连接 器 。 请 参见 “配置 自 定义 连接 器 "关于 如 何 使 用 和 配置 自 定义 
Jersey 客户 端 传输 连接 器 。 


5.3.2. Creating and configuring a Client 
instance 创建 和 配置 客户 端 实例 


JAX-RS 客户 端 API 是 一 个 设计 为 允许 流利 的 编程 模型 。 这 意味 着 ,建设 一 个 客户 端 实例 ,从 中 
创建 一 个 WebTarget, 请 求 调用 是 建立 和 调用 可 以 调用 buo cue 。 流 的 各 个 步骤 将 以 
下 部 分 所 示 。 利 用 客户 端 APL 首先 需要 构建 一 个 客户 端 实例 使 用 一 个 静态 ClientBuilder 工厂 
方法 。 这 是 最 简单 的 例子 


Client client = ClientBuilder.newClient(); 


ClientBuilder 是 JAX-RS API 用 于 创建 新 实例 的 客户 端 。 在 稍微 高 级 的 场景 , ClientBuilder 可 
用 于 配置 额外 的 客户 端 实例 属性 ,如 SSL 传输 设置 


客户 端 实 例 可 以 创建 期 间 通 过 的 ClientConfig 配 置 到 newClient( 可 配置 ) 的 ClientBuilder 工 厂 方 
ClientConfig 实现 可 配置 的 ,因此 它 提供 了 方法 来 注册 供应 商 ( 如 功能 或 单独 的 实体 供应 
商 、 过 滤器 或 拦截 器 ) 和 设置 属性 。 下 面 的 代码 显示 了 一 个 注册 自 定 义 客户 端 过 滤器 : 


ClientConfig clientConfig = new ClientConfig(); 
clientConfig.register(MyClientResponseFilter.class); 
clientConfig.register(new AnotherClientFilter()); 
Client client - ClientBuilder.newClient(clientConfig); 


在 这 个 例子 中 ,过 滤器 是 注册 使 用 ClientConfig.register(...) 方法 。 有 多 个 方法 的 重 载 版 本 ,支持 
iiis Ede J£ Bt A KR EH] © — €. ClientConfig 实例 配置 , 它 可 以 传递 到 ClientBuilder 创建 预 
置 的 客户 端 实 例 。 


注意 ,Jersey ClientConfig 支持 可 配置 的 流利 的 API 模 型 。 与 配置 一 个 新 的 客户 端 实例 的 代码 也 
可 以 写 使 用 更 紧凑 的 样式 如 下 所 示 。 


Client client = ClientBuilder.newClient(new ClientConfig() 
.register(MyClientResponseFilter.class) 
.register(new AnotherClientFilter()); 


利用 这 种 紧凑 模式 的 能 力 是 内 在 所 有 JAX-RS 和 Jersey 客户 端 API 组 件 。 


自 客 户 端 实现 可 配置 接口 , 它 甚 至 可 以 进一步 配置 之 后 创建 的 。 更 重要 的 是 ,任何 配置 更 改 做 一 
个 客户 端 实例 不 会 影响 ClientConfig 实例 ,用 于 提供 初始 客户 端 实例 配置 在 实例 创建 的 时 间 。 
下 一 段 代码 展示 了 一 个 配置 现 有 的 客户 端 实例 。 


client.register(ThirdClientFilter.class); 


类 似 于 之 前 的 例子 ,因为 Client.register(...) 方法 支持 流利 的 APl, 可 以 链接 多 个 客户 机 实例 配置 
调用 : 


client.register(FilterA.class) 
.register(new FilterB()) 
.property("my-property", true); 


getConfiguration() 方法 可 以 使 用 来 获得 当前 配置 的 客户 端 实例 。 


ClientConfig clientConfig = new ClientConfig(); 
clientConfig.register(MyClientResponseFilter.class); 
clientConfig.register(new AnotherClientFilter()); 

Client client - ClientBuilder.newClient(clientConfig); 
client.register(ThirdClientFilter.class); 

Configuration newConfiguration - client.getConfiguration(); 


在 代码 中 ,一 个 额外 的 MyClientResponseFilter 3€ f» AnotherClientFilter 实例 注册 进 
clientConfig。 然 后 clientConfig 被 用 来 构造 一 个 新 的 客户 端 实例 。 添 加 了 ThirdClientFilter 分 
别 构 造 客户 端 实例 。 这 并 不 影响 原 clientConfig 所 代表 的 配置 od nes 
从 客户 端 检索 。 该 配置 包含 所 有 三 个 注册 过 滤器 而 原始 clientConfig 实例 仍然 只 — 滤 
器 。 另 外 ,创建 与 clientConfig newConfiguration 从 客户 端 实例 Lek RARE Po i BC B 
图 。 外 的 配置 变化 也 反映 在 newConfiguration 客户 端 实例 。newConfiguration 74 3E 
的 客户 端 配置 ,而 不 是 复制 配置 状态 。 这 些 原 则 是 重要 的 客户 端 API|, 也 将 在 当中 使 用 。 
iid 您 可 所 有 客户 建立 一 个 公共 基础 配置 (在 我 们 的 例子 中 是 clientConfig ), 然 后 再 利用 
这 常见 的 配置 实例 配置 多 个 客户 机 实例 ,可 以 进一步 专业 化 。 类 似 地 ,您 可 以 使 用 现 有 的 客户 端 
实例 配置 配置 另 一 个 客户 端 实 例 , 而 不 必 担 心 任何 副作用 在 原始 客户 端 实例 。 


5.3.3. Targeting a web resource 针对 网 络 资源 
客户 端 实例 创建 WebTarget 


WebTarget webTarget = client.target("http://example.com/rest"); 


客户 端 包含 几 个 目标 (..,) 方 法 ,允许 创建 WebTarget 实例 。 在 本 例 中 我 们 使 用 目标 uri (String) 
版 本 。 uri 作为 字符 囊 传递 到 方法 有 针对 性 的 Web 资源 的 uri。 在 更 复杂 的 场景 ,这 可 能 是 整个 
RESTful 应 用 程序 的 上 下 文 根 URI,WebTarget 实例 代表 个 人 资源 的 目标 可 以 派生 和 单独 配 

置 。 这 是 可 能 的 ,因为 JAX-RS WebTarget 还 实现 了 可 配置: 


WebTarget webTarget = client.target("http://example.com/rest"); 
webTarget.register(FilterForExampleCom.class); 


JAX-RS 客户 端 API 中 使 用 的 配置 原则 适用 于 WebTarget 。 每 个 WebTarget 实例 配置 都 继承 
自 它 的 父亲 (客户 端 或 另 一 个 web 目标 ), 可 以 进一步 都 不 影响 父 组 件 的 配置 。 在 这 种 情况 

下 ,FilterForExampleCom 将 只 在 webTarget 而 不 是 在 客户 端 注册 。 因 此 ,客户 仍然 可 以 用 来 创 
建新 的 WebTarget 实例 指向 其 他 uri 仅 使 用 普通 客户 端 配置 ,不 属于 FilterForExampleCom 过 


xs BB 
滤器 。 


5.3.4. Identifying resource on WebTarget 识别 资 


让 我 们 假设 我 们 有 一 个 webtarget 指向 "http://example.com/rest" 的 URI， 代 表 着 一 个 
RESTful 应 用 上 下 文 根 有 资源 暴露 在 URI 为 "http://example.com/rest/resource"。 正 如 已 经 提 
到 的 ， 一 个 WebTarget 实例 可 以 用 来 获得 其 他 网 站 的 目标 。 使 用 下 面 的 代码 定义 一 个 路 径 的 


WebTarget resourceWebTarget = webTarget.path("resource"); 


现在 的 resourceWebTarget 指向 URI 的 资源 "http://example.com/rest/resource"。 如 果 我 们 再 
次 配置 [esourceWebTarget 对 特定 资源 的 过 滤器 ， 它 不 会 影响 原始 WebTarget 实例 。 然 而 ， 
过 滤器 FilterForExampleCom 注册 仍 将 继承 的 创建 于 webTarget 的 resourceWebTarget。 这 
种 机 制 多 许 你 共享 有 关 资 源 的 常见 的 配置 (通常 做 法 是 保存 在 相同 的 URI 根 ， 在 我 们 示例 中 
是 用 webTarget 实例 表示 ) ， 同 时 允许 进一步 配置 基于 每 个 资源 的 特定 要 求 的 特定 配置 。 继 
承 相 同 的 配置 原则 (允许 普通 配置 的 传播 ) FORA (允许 个 人 配置 定制 ) 适用 于 下 面 讨论 的 
所 有 JAX-RS 客户 端 API 组 件 。 


假设 有 个 子 资源 “http://example.com/rest/resource/helloworld" ， 可 以 驱动 一 个 WebTarget 
ibd: 


WebTarget helloworldWebTarget = resourceWebTarget.path("helloworld"); 


让 我 们 假设 helloworld 资源 接受 查询 参数 用 于 GET 请 求 ,定义 了 问候 消息 。 下 一 个 代码 片段 显 
示 了 一 个 代码 ， 通 过 定义 查询 参数 的 创建 一 种 新 的 WebTarget 。 


WebTarget helloworldwebTargetwithQueryParam = 
helloworldwebTarget.queryParam("greeting", "Hi World!"); 


请 注意 ， 除 了 方法 可 以 推导 出 新 的 基于 URI 的 路 径 或 查询 参数 WebTarget 实例 ，JAX-RS 
webtarget API 也 包含 矩阵 参数 的 方法 。 


5.3.5. Invoking a HTTP request 调用 一 个 HTTP 


请 求 


现在 要 调用 一 个 GET HTTP 请 求 到 一 个 已 经 创建 的 web target 上 。 开 始 构建 一 个 新 的 
HTTP 请 求 调 用 ， 首 先 要 创建 一 个 新 的 Invocation.Builder 


Invocation.Builder invocationBuilder = 
helloworldwebTargetWithQueryParam. request (MediaType. TEXT_PLAIN_TYPE); 
invocationBuilder.header("some-header", "true"); 


通过 WebTarget 的 其 中 一 个 请 求 方法 来 创建 一 个 invocation builder 实例 。 这 些 方法 接收 的 参 
数 可 以 让 你 定义 返回 资源 的 媒体 类 型 。 我 们 这 里 假设 是 "text/plain" 类 型 ， 告 诉 Jersey 添加 一 
个 Accept: text/plain HTTP header 到 我 们 的 请 求 。 


invocationBuilder 是 用 来 设置 请 求 特定 的 参数 ， 这 里 我 们 可 以 给 请 求 的 header 设置 cookie 参 
数 ， 就 是 例子 中 的 "some-header" ° 


现在 可 以 调用 请 求 了 。 我 们 有 2 个 选项 。 可 以 使 用 Invocation.Builder 构建 一 个 通用 的 
Invocation 实例 ， 迟 点 调用 。 使 用 Invocation 可 以 如 例子 中 所 述 的 设置 额外 的 请 求 属性 ， 使 
用 通用 的 JAX-RS Invocation API 来 调用 批量 请 求 而 无 需 了 解 细节 ( 比如 HTTP 方法 , 配置 
F) 。 任 何 设置 在 调用 实例 的 属性 ， 都 能 在 请 求 进 程 中 都 读 到 。 举 例 ， 在 自 定 义 
ClientRequestFilter 调 用 getProperty() 方法 提供 ClientRequestContext 来 读 请 求 属性 。 注 
意 ， 请 求 属性 和 Configurable 上 的 配置 属性 是 不 同 的 。 正 如 之 前 提 到 的 ，lInvocation 实例 提 
供 了 通用 的 invocation API 来 调用 HTTP 请 求 ， 同 步 或 异步 。 详 见 Chapter 10. 
Asynchronous Services and Clients 异步 服务 器 和 客户 端 异 步调 用 。 


如 果 你 不 想 调 用 它们 之 前 做 任何 批 处 理 您 的 HTTP 请 求 调用 ， 还 有 一 个 更 方便 的 方法 ， 可 以 
直接 从 一 个 调用 生成 器 实例 用 来 调用 你 的 请 求 。 这 种 方法 如 下 : 


Response response = invocationBuilder.get(); 


示例 中 的 代码 很 短 ， 但 执行 多 个 动作 。 首 先 ， 从 invocationBuilder 构建 了 请 求 ， 可 能 是 
http://example.com/rest/resource/helloworld?greeting="Hi%20Worldl"， 包 含 了 some- 
header: true 和 Accept: text/plain 头 文 件 ， 


请 求 将 通过 所 有 配置 请 求 过 滤器 (AnotherClientFilter, ThirdClientFilter 和 
FilterForExampleCom) 。 一 旦 通过 滤波 器 处 理 ， 请 求 将 被 发 送 到 远程 资源 。 假 设 资源 然后 返 
回 一 个 HTTP 200 消息 的 一 个 纯 文 本 响应 ， 内 容 包 含 在 请 求 中 发 送 问 候 查 询 参 数 的 值 。 现 在 
我 们 可 以 看 到 返回 的 响应 : 


System.out.println(response.getStatus()); 
System.out.println(response.readEntity(String.class)); 


控制 台 输 出 : 


200 
Hi World! 


正如 所 见 ， 请 求 被 成 功 执行 返回 了 实体 "Hi Worldl"。 注 意 ， 因 为 我 在 资源 目标 配置 了 
od * 4 response.readEntity(String.class) 调用 时 ， 返 回 的 响应 ， 从 远 
程 端点 通过 响应 过 滤器 链 (包括 MyClientResponseFilter) 和 实体 拦截 器 链 和 最 后 一 个 适当 的 
ee 位 于 读 取 响 应 内 容 字 节 从 响应 流 到 一 个 Java Fi P EA o 
Chapter 9. Filters and Interceptors 过 滤器 和 拦截 器 ， 请 求 和 响应 的 过 滤器 和 实体 拦截 器 


想象 下 ， 你 要 调用 POST 请 求 ， 但 不 带 任何 参数 ， 仅 仅 需要 使 用 helleworldWebTarget 3: 
例 ， 将 post() 替换 get() : 


Response postResponse = 
helloworldwebTarget.request(MediaType.TEXT PLAIN TYPE) 
.post(Entity.entity("A string entity to be POSTed", MediaType.TEXT PLA 
IN)); 


5.3.6. Example summary 实例 摘要 


在 之 前 例子 的 代码 


Example 5.2. Using JAX-RS Client API 


ClientConfig clientConfig = new ClientConfig(); 
clientConfig.register(MyClientResponseFilter.class); 
clientConfig.register(new AnotherClientFilter()); 


Client client - ClientBuilder.newClient(clientConfig); 
client.register(ThirdClientFilter.class); 


WebTarget webTarget - client.target("http://example.com/rest"); 

webTarget.register(FilterForExampleCom.class); 

WebTarget resourceWebTarget - webTarget.path("resource"); 

WebTarget helloworldwebTarget = resourceWebTarget.path("helloworld"); 

WebTarget helloworldwebTargetWithQueryParam = 
helloworldWebTarget.queryParam("greeting", "Hi World!"); 


Invocation.Builder invocationBuilder - 
helloworldWebTargetWithQueryParam.request(MediaType.TEXT PLAIN TYPE); 
invocationBuilder.header("some-header", "true"); 


Response response = invocationBuilder.get(); 
System.out.println(response.getStatus()); 
System.out.println(response.readEntity(String.class)); 


现在 我 们 可 以 尝试 利用 fluent API 的 风格 ， 在 一 个 更 紧凑 的 方式 写 代码 。 


Example 5.3. Using JAX-RS Client API fluently 


Client client = ClientBuilder.newClient(new ClientConfig() 
.register(MyClientResponseFilter.class) 
.register(new AnotherClientFilter())); 


String entity - client.target("http://example.com/rest") 
.register(FilterForExampleCom.class) 
.path("resource/helloworld") 

.queryParam( "greeting", "Hi World!") 
.request(MediaType.TEXT PLAIN TYPE) 
.header("some-header", "true") 
.get(String.class); 


上 面 的 代码 做 同样 的 事情 。 这 种 快捷 的 方法 让 你 指定 (如果 成 功 返 回 一 个 HTTP 响应 状态 码 响 
应 实体 2XX ) 应 为 Java 字符 串 返 回 类 型 。 这 个 紧凑 的 示例 演示 了 JAX-RS ŽP API 另 一 
个 优点 。 流 畅 的 JAX-RS 客户 端 API 很 方便 ， 特 别 是 简单 的 用 法 中 。 这 是 另 一 个 非常 简单 的 
GET 请 求 返回 一 个 字符 串 表 示 形 式 〈 实 体 ) 


String responseEntity = ClientBuilder.newClient() 
.target("http://example.com").path("resource/rest") 
.request().get(String.class) 


5.3 客户 端 APL 总 览 
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6.1. Motivation for Reactive Client Extension 
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6.2. Usage and Extension Modules 
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6.3. Supported Reactive Libraries 
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6.4. Implementing Support for Custom Reactive Libraries (SPI) 
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6.5. Examples 
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Chapter 7. Representations and 
Responses 表示 与 响应 


7.1. Representations and Java Types 表示 
与 Java 类 型 


前 面 提 到 的 @Produces 和 @Consumes 注 解 称 为 实体 的 媒体 类 型 表示 。 上 面 的 例子 描述 资源 
方法 能 够 消耗 和 /或 产生 String Java 类 型 的 不 同 的 媒体 类 型 。 这 种 方法 很 容易 理解 和 相对 简单 
对 于 应 用 于 简单 的 用 例 来 说 。 


还 涵盖 其 他 情况 下 ,处 理 non-String (JELA) 数据 ， 例 如 处 理 数 据 存储 在 文件 系统 ,等 等 ， 
JAX-RS 实现 也 需要 支持 其 他 类 型 的 媒体 类 型 转换 ,non-String ( 非 文 本 ) Java 类 型 都 得 到 了 
利用 。 下 面 是 一 个 简短 的 清单 , 开 箱 即 用 的 支持 Java 类 型 的 媒体 类 型 : 


。 所 有 媒体 类 型 (/) 
o byte[] 
o java.lang.String 
o java.io.Reader (inbound only) 
o java.io.File 
o javax.activation.DataSource 
o javax.ws.rs.core.StreamingOutput (outbound only) 
e XML 媒体 类 型 (text/xml, application/xml and application/...+xml) 
o javax.xml.transform.Source 
o javax.xml.bind. JAXBElement 
o 应 用 了 JAXB 类 的 应 用 (使 用 了 @XmiRootElement 或 者 @XmlType 的 类 型 ) 
e Form 表单 内 容 (application/x-www-form-urlencoded) 
o MultivaluedMap 
e 纯 文本 (text/plain) 
o java.lang.Boolean 
o java.lang.Character 
o java.lang.Number 


不 同 于 方法 参数 与 请 求 参数 的 提取 相关 联 ,方法 参数 与 所 消耗 的 表示 相关 联 不 需要 注释 。 换 名 
话说 表示 (实体 ) 的 参数 不 需要 特定 的 “实体 "注解 。 一 个 没有 注解 的 方法 参数 就 是 一 个 实体 。 最 
大 的 一 个 这 样 的 未 注解 的 方法 的 参数 可 能 存在 自从 有 可 能 是 最 大 的 一 个 这 样 的 表示 在 请 求 时 
发 送 。 
产生 的 表示 对 应 于 资源 方法 返回 的 是 什么 。 例 如 JAX-RS 使 它 简单 的 产生 例 图 像 文件 实例 ， 
如 下 : 


Example 7.1. Using File with a specific media type to produce a response 


@GET 

@Path("/images/{image}") 

@Produces("image/*") 

public Response getImage(@PathParam("image") String image) { 
File f = new File(image); 


if (!f.exists()) { 
throw new WebApplicationException(404); 


} 


String mt = new MimetypesFileTypeMap().getContentType(f); 
return Response.ok(f, mt).build(); 


文件 类 型 同样 适用 于 消耗 一 个 表示 (请求 实体) 。 在 这 种 情况 下 ， 临 时 文件 将 从 传 入 的 请 求 
实体 创建 ， 并 且 作 为 参数 传 给 资源 的 方法 。 


Content-Type 响应 头 (如 果 没 有 设置 编程 方式 ， 在 下 节 介 绍 ) 将 自动 设置 基于 媒体 类 型 通 
@Produces 声明 。 例 如 下 面 的 方法 ， 当 允许 多 个 输 ee 时 ， Eee 
用 : 


@GET 
@Produces({"application/xml", "application/json"}) 
public String doGetAsXmlOrJson() { 


如 果 application/xml 是 最 可 接受 的 媒体 类 型 定义 在 请 求 中 (例如 ， 如 头 Accept: 
application/xml) ， 则 响应 头 Content-Type 将 被 设 为 application/xml 


7.2. Building Responses 构建 响应 


有 时 有 必要 返回 响应 HTTP 请 求 的 额外 信息 。 这 些 信 息 可 能 是 使 用 Response 和 
Response.ResponseBuilder 来 构建 并 返回 。 例 如 ,一 个 常见 的 RESTful 模式 创建 一 个 新 的 资 
源 是 支持 一 个 POST 请 求 ,返回 一 个 201(Created) 状 态 码 和 其 值 是 新 创建 的 资源 的 URI 的 
Location header 。 可 能 实现 如 下 : 


Example 7.2. Returning 201 status code and adding Location header in response to POST 
request 


@POST 
QConsumes ("application/xml") 
public Response post(String content) { 
URI createdUri - ... 
create(content); 
return Response.created(createdUri).build(); 


} 


在 上 面 没 有 返回 产生 的 表示 ， 这 可 以 通过 建立 一 个 实体 作为 响应 的 一 部 分 来 实现 


Example 7.3. Adding an entity body to a custom response 


@POST 
QConsumes ("application/xml") 
public Response post(String content) { 
URI createdUri - ... 
String createdContent - create(content); 
return Response.created(createdUri).entity(Entity.text(createdContent)).build(); 


} 


响应 构建 提供 其 他 功能 ， 如 设置 实体 标签 和 最 后 修改 日 期 的 表示 。 


7.3. WebApplicationException and 
Mapping Exceptions to Responses Jr € 


前 面 提 到 的 HTTP 响应 ， 都 是 编程 构建 的 。 可 以 使 用 相同 的 机 制 来 返回 HTTP. 错误 ， 例 如 在 
try-catch 块 处 理 异 常 。 然 而 ， 更 好 地 与 Java 编程 模型 一 致 ，JAX-RS 允许 定义 Java HH 到 
HTTP 错误 响应 的 直接 映射 。 


下 面 的 示例 演示 了 当 资源 的 方法 返回 一 个 错误 的 HTTP 响应 给 客户 端 时 ， 抛 出 
CustomNotFoundException : 


Example 7.4. Throwing exceptions to control response 


@Path("items/{itemid}/") 
public Item getItem(@PathParam("itemid") String itemid) { 
Item i = getItems().get(itemid); 
if (i == null) ( 
throw new CustomNotFoundException("Item, " + itemid + ", is not found"); 


} 


return i; 


} 


这 是 个 继承 自 WebApplicationException 的 具体 异常 应 用 ， 构 建 了 一 个 404 状态 的 HTTP A 
应 和 可 选 的 消息 作为 响应 的 内 容 : 


Example 7.5. Application specific exception implementation 


public class CustomNotFoundException extends WebApplicationException { 


/** 

* Create a HTTP 404 (Not Found) exception. 

"f 

public CustomNotFoundException() { 
super(Responses.notFound().build()); 

} 


Jee 
* Create a HTTP 404 (Not Found) exception. 
* @param message the String that is the entity of the 404 response. 
v 
public CustomNotFoundException(String message) { 
super(Response.status(Responses.NOT FOUND). 
entity(message).type("text/plain").build()); 
} 
} 


在 其 他 情况 下 ， 它 可 能 不 适合 把 WebApplicationException 实 例 ， 或 扩展 了 
WebApplicationException 类 的 异常 抛 出 ， 相 反 ， 它 可 能 是 可 取 的 存在 的 异常 响应 map 。 对 
于 这 样 的 情况 可 以 使 用 自 定 义 异 常 映射 提供 者 。 供 应 者 必须 实现 ExceptionMapper 接口 。 例 
如 ， 下 面 一 个 EntityNotFoundException map 到 HTTP 404(Not Found) 的 响应 : 


Example 7.6. Mapping generic exceptions to responses 


@Provider 
public class EntityNotFoundMapper implements ExceptionMapper<javax.persistence.EntityN 
otFoundException> { 
public Response toResponse(javax.persistence.EntityNotFoundException ex) ( 
return Response.status(404). 

entity(ex.getMessage()). 

type("text/plain"). 

build(); 


上 面 的 类 使 用 了 @Provider 注解 ,这 个 声明 的 类 是 JAX-RS 运行 时 。 这 样 的 类 可 以 被 添加 到 配 
置 了 的 Application 实例 的 类 的 集合 中 。 当 应 用 程序 抛 出 一 个 EntityNotFoundException 时 ， 
EntityNotFoundMapper 实例 的 toResponse 方法 将 被 调用 。 


Jersey 支持 扩展 映射 器 的 异常 。 这 些 扩 展映 射 器 必须 实现 org.glassfish.jersey.spi 。 
ExtendedExceptionMapper 接口 。 另 外 这 个 接口 定义 方法 isMappable(Throwable), 将 被 
Jersey 运行 时 调用 当 异 常 抛 出 并 且 这 个 供应 者 被 认为 是 可 映射 基于 异常 类 型 。 使 用 这 种 方 
法 ， 异 常 的 提供 者 可 以 拒绝 异常 映射 在 方法 toResponse 被 调用 之 前 。 提 供 者 可 以 例如 检查 异 
常 参数 ,基于 他 们 返回 false, 和 让 其 他 供应 者 选择 异常 映射 。 


7.3 WebApplicationException and Mapping Exceptions to Response 
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7.4. Conditional GETs and Returning 304 
(Not Modified) Responses 条 件 GET 和 返回 
3043 


条 件 GET 是 一 个 伟大 的 方式 来 减少 带宽 ,并 可 能 提高 对 服务 器 端 性 能 ,根据 信息 用 于 确定 条 件 
是 如 何 计算 出 来 的 。 一 个 设计 良好 的 网 站 例如 返回 304 (Not Modified) 响应 给 它 提供 的 静态 图 
像 服务 。 


JAX-RS 使 用 上 下 文 接 口 Request 来 提供 对 条 件 GET 的 支持 。 
下 面 的 例子 显示 了 对 条 件 GET 的 支持 : 


Example 7.7. Conditional GET support 


public SparklinesResource( 
@QueryParam("d") IntegerList data, 
@DefaultValue("0,100") @QueryParam("limits") Interval limits, 
@Context Request request, 
@Context UriInfo ui) ( 
if (data == null) { 
throw new WebApplicationException(400); 
} 


this.data = data; 
this.limits = limits; 


if (!limits.contains(data)) { 
throw new WebApplicationException( 400); 
} 


this.tag = computeEntityTag(ui.getRequestUri()); 


if (request.getMethod().equals("GET")) { 
Response.ResponseBuilder rb = request.evaluatePreconditions(tag); 
if (rb != null) { 
throw new WebApplicationException(rb.build()); 
à 
} 
} 


SparklinesResouce 根 资源 类 从 请 求 URI 计算 实体 的 标签 ， 然 后 调用 带 有 实体 标签 的 
request.evaluatePreconditions)。 如 果 客 户 端 请 求 包含 一 个 If-None-Match 头 值 包含 相同 实体 
标签 被 计算 ， 那 么 evaluatePreconditions 返回 一 个 预先 填写 evaluatepreconditions) 响应 ， 


带 着 304 状态 代码 和 实体 标签 设置 ， 可 以 建立 和 恢复 。 和 否则 ，evaluatepreconditions) 返回 
null， 正 常 的 响应 可 以 返回 。 


注意 ， 在 这 个 例子 中 ， 一 个 资源 类 的 构造 函数 是 用 来 执行 ， 否 则 可 能 被 复制 到 每 个 资源 的 方 
法 调用 动作 。 资 源 美的 生命 周期 是 每 个 请 求 这 意味 着 资源 的 实例 为 每 个 请 求 创建 的 ， 因 此 可 
以 用 请 求 参数 ， 例 如 更 改 请 求 处 理 通过 抛 出 异常 ， 就 像 在 这 个 例子 所 示 。 


Chapter 9. Support for Common Media 
Type Representations 支持 常用 媒体 类 型 


9.1. JSON 


Jersey JSON 支持 之 际 ,一 组 扩展 模块 ,每 个 模块 包含 一 个 功能 的 实现 ,需要 注册 到 您 的 配置 实 
例 (客户 机 /服务 器 )。 有 多 个 框架 提供 支持 ISON 处 理 和 /或 JSON-to-Java 绑 定 。 下 面 列 出 的 
模块 提供 支持 JSON 表示 通过 整合 个 人 JSON 框架 Jersey。 目 前 ,Jersey 集成 了 以 下 模块 提 
供 JSON 支持 : 


e MOXy-JSON 默认 通过 MOXy RAB > HH Jersey 2.0 以 来 的 应 用 程序 是 支持 ISON 
绑 定 首选 方法 。 当 JSON MOXy 模块 在 类 路 径 ,Jersey 将 自动 发 现 模块 和 无 缝 地 支持 
JSON 绑 定 支持 通过 MOXy 在 应 用 程序 中 。( 见 4.3 节 “自动 发 现 功能 "。 

Java API 为 JSON 处 理 (JSON-P) 

e Jackson 


Jettison 


9.1.1. Approaches to JSON Support 支持 JSON 
方法 
每 个 上 述 扩展 模块 使 用 一 个 或 多 个 可 用 的 三 种 基本 方法 在 处 理 JSON 表 示 : 


e 基于 POJO 的 JSON RE 
e 基于 JAXB 的 JSON HE 
e 低级 的 JSON 解 析 和 处 理 支持 


ee 的 ,允许 您 将 任何 Java 对 象 映 射 到 JSON, 反 之 亦 然 。 其 他 两 种 方法 限 

你 在 Java 类 型 资源 方法 可 以 生产 和 /或 使 用 。 基 于 JAXB 方法 是 有 用 的 ,如 果 你 打算 使 用 
JAXB 的 某 些 特性 和 支持 XML 和 JSON 表示 。 最 后 ,低级 方法 给 你 最 好 的 细 粒 度 控制 输出 的 
JSON 数据 格式 。 


9.1.1.1. POJO support 基于 POJO 


POJO 的 支持 是 最 简单 的 方法 将 Java 对 象 转换 为 ISON 和 转 回 去 。 媒体 模块 ,支持 这 种 方法 
是 MOXy 和 Jackson 


9.1.1.2. JAXB based JSON support 基于 JAXB 


采取 这 种 方法 可 以 节省 大 量 的 时 间 , 如 果 你 想 轻 松 地 生成 /使 用 JSON 和 XML 数据 格式 。 与 
JAXB bean 你 将 能 够 使 用 相同 的 Java 模型 生成 JSON 和 XML 表示 。 与 这 样 一 个 合作 的 另 一 
个 优点 是 简单 模型 和 API 在 Java SE 平台 的 可 用 性 。 JAXB 使 用 注解 的 POJO, 这 些 可 以 处 理 


简单 的 Java bean。 


基于 JAXB 方法 的 一 个 缺点 可 能 是 如 果 你 需要 使 用 一 个 非常 具体 的 JSON 格式 。 然 后 可 能 很 
难 找到 一 个 合适 的 方法 来 得 到 这 样 一 个 格式 生产 和 消费 。 这 是 一 个 原因 提供 了 许多 配置 选项 
这 样 你 就 可 以 控制 如 何 JAXB bean 序列 化 和 反 序列 化 。 额 外 的 配置 选项 但 是 需要 你 更 详细 的 


了 解 您 所 使 用 的 框架 。 
下 面 是 一 个 非常 简单 的 例子 ,来 说 明 JAXB bean 可 能 看 起 来 像 。 


Example 9.1. Simple JAXB bean implementation 


QXmlRootElement 

public class MyJaxbBean { 
public String name; 
public int age; 


public MyJaxbBean() (3 // JAXB needs this 


public MyJaxbBean(String name, int age) { 
this.name - name; 
this.age - age; 


使 用 上 面 的 JAXB bean 生成 JSON 数据 格式 资源 方法 ,然后 一 样 简单 : 


Example 9.2. JAXB bean used to generate JSON representation 


@GET 
@Produces("application/json") 
public MyJaxbBean getMyBean() { 

return new MyJaxbBean("Agamemnon", 32); 


} 


注意 ,JSON @Produces 注释 中 指定 特定 的 mime 类 型 ,MyJaxbBean 的 方法 返回 


例 ,JAXB 能 够 处 理 。 生 成 的 ISON 在 这 种 情况 下 会 看 起 来 像 : 


{"name" : "Agamemnon", "age":"32"} 


正确 使 用 JAXB 注解 本 身 可 以 控制 一 定 ISON 格式 输出 。 具 体 来 说 ,直接 通 


一 个 


过 使 用 JAXB 注释 


很 容易 做 到 重 命名 和 删除 属性 。 例 如 ,下 面 的 例子 描述 了 上 述 MyJaxbBean 变化 将 导致 


{"king":"Agamemnon"} JSON 输 出 。 


Example 9.3. Tweaking JSON format using JAXB 


QXmlRootElement 
public class MyJaxbBean { 


QXmlElement (name="king") 
public String name; 


QXmlTransient 
public int age; 


// several lines removed 


媒体 模块 ,支持 这 种 方法 是 MOXy, Jackson, Jettison 


9.1.1.3. Low-level based JSON support 低级 的 JSON 解 析 和 处 
理 支 持 


JSON 处 理 API 是 一 个 新 的 标准 API 进行 解析 和 处 理 ISON 结构 以 类 似 的 方式 ,SAX 和 StAX 
解析 器 提供 对 XML 。 这 个 API Java EE 7 和 后 来 的 一 部 分 。 另 一 个 JSON 解析 /处 理 抛弃 
框架 提供 的 APl。 这 两 种 api 提供 一 个 低级 访问 生产 和 消费 ISON 数据 结构 。 采 用 这 种 低级 
的 方法 你 会 使 用 JsonObject( 或 JsonObject) 和 /或 JsonArray (或 分 别 JsonArray ) 类 在 处 理 
JSON 数 据 表示 。 


这 些 低 级 api 的 最 大 优势 是 ,你 会 得 到 完全 控制 和 消费 产生 的 JSON 格式 。 你 也 能 够 生产 和 消 
费 非常 大 的 JSON 结构 使 用 流 ISON 解析 器 /生成 器 api。 另 一 方面 ,处 理 您 的 数据 模型 对 象 可 
能 会 更 复杂 ,相对 于 POJO 或 基于 JAXB 绑 定 方 法 。 差 异 是 描述 在 以 下 代码 片段 。 


基于 JAXB HE Y k 


Example 9.4. JAXB bean creation 
MyJaxbBean myBean = new MyJaxbBean("Agamemnon", 32); 


当 你 构建 一 个 JAXB bean H > JSON 5 Xi {"name":"Agamemnon", "age":32} 


现在 构建 一 个 等 价 的 JsonObject / JsonObject( 生 成 的 JSON 的 表达 式 ), 您 需要 几 行 代码 。 下 面 
的 例子 说 明了 如 何 构 造 相同 的 JSON 数据 使 用 标准 的 Java EE 7 JSON 处 理 API © 


JsonObject myObject = Json.createObjectBuilder() 


.add("name", "Agamemnon" ) 
.add("age", 32) 
.build(); 


最 后 看 下 使 用 Jettison 来 做 同样 的 事 ， 


Example 9.6. Constructing a JSONObject (Jettison) 


JSONObject myObject = new JSONObject(); 


try { 
myObject.put("name", "Agamemnon" ); 
myObject.put("age", 32); 

} catch (JSONException ex) { 
LOGGER. log(Level.SEVERE, "Error ...", ex); 


} 


媒体 模块 ,支持 低级 JSON 解析 和 生成 方法 是 Java API for JSON Processing (JSON-P) 和 
Jettison。 除 非 你 有 强烈 的 理由 使 用 非 标 准 抛 Jettison API, 我 们 推荐 您 使 用 新 标准 Java API for 
JSON Processing (JSON-P) API ° 


9.1.2. MOXy 


9.1.2.1. Dependency 
需要 添加 jersey-media-moxy 依赖 库 在 你 的 pom.xml 来 使 用 MOXy 


<dependency> 
<groupId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-moxy</artifactId> 
<version>2.16</version> 

</dependency> 


不 用 maven 的 话 ， 要 确保 所 有 需要 的 库 在 类 路 径 下 ， 建 jersey-media-moxy 


9.1.2.2. Configure and register 配置 和 注册 


如 上 所 述 在 见 4.3 节 ,自动 发 现 功能 "以 及 在 本 章 早 些 时 候 ,MOXYy 模块 是 您 不 需要 显 式 地 注册 它 
的 特性 (MoxyJsonFeature) 在 您 的 客户 端 /服务 器 配置 的 模块 之 一 ， 这 个 特性 是 自动 发 现 和 注册 
时 将 jersey-media-moxy 模块 添加 到 您 的 类 路 径 。 


自动 发 现 的 jersey-media-moxy 模块 定义 了 几 个 属性 ,可 用 于 控制 自动 登记 
MoxyJsonFeature( 除 了 通用 CommonProperties.FEATURE_AUTO_DISCOVERY_DISABLE 
一 个 客户 机 /服务 器 变量 ): 


e CommonProperties.MOXY JSON FEATURE DISABLE 
e ServerProperties. MOXY JSON FEATURE DISABLE 
e ClientProperties.MOXY JSON FEATURE DISABLE 


注意 手动 注册 其 他 Jersey JSON 提 供 者 功能 (除了 Java API for JSON Processing (JSON-P)) 
禁用 MoxyJsonFeature 的 自动 启用 和 配置 。 


配置 MOXy 所 提供 的 MessageBodyReader / MessageBodyWriter 您 可 以 简单 地 创建 一 个 
MoxyJsonConfig 实例 ,并 设置 必要 的 属性 的 值 。 最 常见 的 属性 可 以 使 用 一 个 特定 的 方法 来 设 
置 属性 的 值 也 可 以 使 用 更 通用 的 方法 来 设置 属性 : 


设置 Marshaller 和 





e MoxyJsonConfig#property(java.lang.String, java.lang.Object)) 
Unmarshaller 属 性 值 





e MoxyJsonConfig#marshallerProperty(java.lang.String, java.lang.Object)) 设置 
Marshaller 属性 值 
e MoxyJsonConfig#unmarshallerProperty(java.lang.String, java.lang.Object)) 设置 





Unmarshaller 属 性 值 


Example 9.7. MoxyJsonConfig - Setting properties. 


final Map<String, String» namespacePrefixMapper = new HashMap<String, String»(); 
namespacePrefixMapper.put("http://www.w3.org/2001/XMLSchema-instance", "xsi"); 


final MoxyJsonConfig configuration = new MoxyJsonConfig() 
. setNamespacePrefixMapper (namespacePrefixMapper ) 
. setNamespaceSeparator(':'); 


为 了 使 MoxyJsonConfig 对 MOXy 可 见 , 您 需要 创建 并 注册 ContextResolver 在 您 的 客户 端 / 服 
务 器 的 代码 。 


Example 9.8. Creating ContextResolver 


final Map<String, String> namespacePrefixMapper = new HashMap<String, String>(); 
namespacePrefixMapper.put("http://www.w3.org/2001/XMLSchema-instance", "xsi"); 


final MoxyJsonConfig moxyJsonConfig = MoxyJsonConfig() 
. setNamespacePrefixMapper (namespacePrefixMapper ) 
.setNamespaceSeparator(':'); 


final ContextResolver«MoxyJsonConfig» jsonConfigResolver - moxyJsonConfig.resolver(); 


配置 属性 传递 给 底层 MOXyJsonProvider 的 另 一 种 方法 是 设置 直接 到 您 的 配置 实例 (参见 下 面 
的 一 个 例子 )。 这 些 都 是 被 属性 设置 覆盖 到 MoxyJsonConfig ° 


Example 9.9. Setting properties for MOXy providers into Configurable 


new ResourceConfig() 
.property(MarshallerProperties.JSON NAMESPACE SEPARATOR, " 
2 


// further configuration 


当 MOXy 的 MessageBodyReader MessageBodyWriter 被 使 用 ， 有 一 些 Jersey 的 属性 被 设 
置 默认 值 


Table 9.1. Default property values for MOXy MessageBodyReader MessageBodyWriter 


javax.xml.bind.Marshaller#JAXB_FORMATTED_OUTPUT 
org.eclipse.persistence.jaxb.JAXBContextProperties#JSON_INCLUDE_ROOT false 
org.eclipse.persistence.jaxb.MarshallerProperties#JSON_MARSHAL_EMPTY_COLLECTIO 
NStrue 
org.eclipse.persistence.jaxb.JAXBContextProperties#JSON_NAMESPACE_SEPARATORor 
g.eclipse.persistence.oxm.XMLConstants#DOT 

Example 9.10. Building client with MOXy JSON feature enabled. 


final Client client = ClientBuilder.newBuilder() 
// The line below that registers MOXy feature can be 
// omitted if FEATURE AUTO DISCOVERY DISABLE is 
// not disabled. 
.register(MoxyJsonFeature.class) 
.register(jsonConfigResolver) 
.build(); 


Example 9.11. Creating JAX-RS application with MOXy JSON feature enabled. 


// Create JAX-RS application. 

final Application application - new ResourceConfig() 
.packages("org.glassfish.jersey.examples.jsonmoxy") 
// The line below that registers MOXy feature can be 
// omitted if FEATURE AUTO DISCOVERY DISABLE is 
// not disabled. 
.register(MoxyJsonFeature.class) 
.register(jsonConfigResolver); 


9.1.2.3. Examples 


Jersey 提供 一 个 JSON MOXy example 如 何 使 用 MOXy 来 消费 /生成 JSON ° 


8.1.3. Java API for JSON Processing (JSON-P) 


8.1.3.1. Dependency 依赖 


使 用 JSON-P 作为 JSON 的 提供 者 需要 添加 jersey-media-json-processing 模块 到 pom.xml 
文件 : 


<dependency> 
<groupiId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-json-processing</artifactId> 
<version>2.16</version> 

</dependency> 


如 果 你 不 使 用 Maven， 要 确保 所 有 需要 的 依赖 关系 ( 见 jersey-media-json-processing) 到 类 的 
路 径 。 


9.1.3.2. Configure and register 配置 和 注册 


正如 见 4.3 节 ， 自动 发 现 功能 "中 提 到 的 ,JSON-Processing 模块 ,您 不 需要 显 式 地 注册 它 的 特性 
OND ee 您 的 客户 端 /服务 器 配置 ， 这 个 特性 是 将 jersey-media-json- 
processing 模块 添加 到 您 的 类 路 径 中 时 自动 发 现 和 注册 时 。 


至 于 其 他 模块 ,jersey-media-json-processing 还 几 个 属性 ,会 影响 JsonProcessingFeature 的 注 
册 (除了 CommonProperties.FEATURE_AUTO_DISCOVERY_DISABLE 等 ): 


e CommonProperties.JSON PROCESSING FEATURE DISABLE 
e ServerProperties. JSON PROCESSING FEATURE DISABLE 
e ClientProperties JSON PROCESSING FEATURE DISABLE 


JSON-P 提供 配置 si gas ba mE E al ， 只 需 提 供 支 持 的 属性 值 添加 
到 配置 实例 (客户 机 /服务 器 )。 目 前 支持 这 些 属性 


e JsonGenerator.PRETTY PRINTING ("javax.json.stream.JsonGenerator.prettyPrinting") 


Example 9.12. Building client with JSON-Processing JSON feature enabled. 


ClientBuilder.newClient(new ClientConfig() 
// The line below that registers JSON-Processing feature can be 
// omitted if FEATURE AUTO DISCOVERY DISABLE is not disabled. 
.register(JsonProcessingFeature.class) 
.property(JsonGenerator.PRETTY PRINTING, true) 


Example 9.13. Creating JAX-RS application with JSON-Processing JSON feature enabled. 


// Create JAX-RS application. 

final Application application - new ResourceConfig() 
// The line below that registers JSON-Processing feature can be 
// omitted if FEATURE AUTO DISCOVERY DISABLE is not disabled. 
.register(JsonProcessingFeature.class) 
.packages("org.glassfish.jersey.examples.jsonp") 
.property(JsonGenerator.PRETTY PRINTING, true); 


9.1.3.3. Examples 


Jersey 提供 了 一 个 JSON Processing 实 例如 何 使 用 JSON-Processing 处 理 消 费 / 生 成 JSON。 


9.1.4. Jackson (1.x and 2.x) 


9.1.4.1. Dependency ‘4k si 
使 用 Jackson 2.x 需 添 加 jersey-media-json-jackson 模块 到 pom.xml: 


<dependency> 
<groupiId>org.glassfish. jersey.media</groupId> 
<artifactId>jersey-media-json-jackson</artifactId> 
<version>2.16</version> 

</dependency> 


使 用 Jackson 1.x 用 法 如 下 : 


<dependency> 
<groupId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-json-jacksoni</artifactId> 
<version>2.16</version> 

</dependency> 


如 果 你 不 使 用 Maven， 要 确保 所 有 需要 的 依赖 关系 ( 见 jersey-media-json-jackson X jersey- 
media-json-jackson) ) 到 类 的 路 径 。 


9.1.4.2. Configure and register 配置 和 注册 


ES 


注意 ,不 同 的 名 称 空 间 ，Jackson 1.x (org.codehaus.jackson) 和 Jackson 2.x 
(com.fasterxml.jackson) 


Jackson JSON 处 理 器 可 以 通 ipd É x 3L Jackson 2 的 ObjectMapper (或 者 Jackson 1 
的 ObjectMapper ) 实例 来 控制 。 能 是 方便 的 ,如 果 你 需要 重新 定义 默认 Jackson 行为 
调整 你 的 JSON 数 据 结 构 。Jackson 2 所 有 特性 的 详细 描述 了 本 指南 的 范围 。 下 面 的 例子 给 

一 个 提示 如 何 写 ObjectMapper (ObjectMappen 实 例 到 你 的 Jersey 的 应 用 程序 。 


如 果 需 要 ,在 你 的 配置 (客户 机 /服务 器 ) 中 ， 为 了 使 用 Jackson 作为 JSON(JAXB/POJO) 提 供 者 
需要 给 ObjectMapper 注 册 JacksonFeature(Jackson1Feature) 和 ContextResolver ° 


Example 9.14. ContextResolver 


@Provider 
public class MyObjectMapperProvider implements ContextResolver<ObjectMapper> ( 


final ObjectMapper defaultObjectMapper; 


public MyObjectMapperProvider() { 
defaultObjectMapper = createDefaultMapper(); 


} 
@Override 
public ObjectMapper getContext(Class<?> type) { 


return defaultObjectMapper; 


} 
} 


private static ObjectMapper createDefaultMapper() { 
final ObjectMapper result = new ObjectMapper(); 
result.configure(Feature.INDENT_OUTPUT, true); 


return result; 


Te oe 
完整 示例 ， 见 来 自 JSON-Jackson 例子 中 的 MyObjectMapperProvider 类 . 
Example 9.15. Building client with Jackson JSON feature enabled. 


final Client client = ClientBuilder.newBuilder() .register(MyObjectMapperProvider.class) /无 
特殊 要 求 无 需 注 册 这 个 .register(JacksonFeature.class) .build(); 


Example 9.16. Creating JAX-RS application with Jackson JSON feature enabled. 


// Create JAX-RS application. final Application application = new ResourceConfig() 
.packages("org.glassfish.jersey.examples.jackson") 
register(MyObjectMapperProvider.class) /无 特殊 要 求 无 需 注册 这 个 
.register(JacksonFeature.class); 


9.1.4.3. Examples 


Jersey 提供 JSON Jackson (2.x) 的 例子 和 JSON Jackson (1.x) 例子 展示 如 何 使 用 Jackson 
消费 /生成 JSON 。 


9.1.5. Jettison 


Jettison 模块 提供 ( 反 ) 序 列 化 JSON 的 JAXB 方法 ， 除 了 使 用 纯 JAXB, 配 置 选项 可 以 设置 在 
一 个 JettisonConfig 实例 。 然 后 实例 可 以 进一步 用 于 创建 JettisonJaxbContext, 作 为 主要 的 配 
置 点 。 通 过 你 的 专业 JettisonJaxbContext to Jersey, 你 将 最 终 需 要 实现 一 个 JAXBContext 
ContextResolver (( 见 下 文 )。 


9.1.5.1. Dependency 依赖 
如 果 使 用 Jettison 需要 添加 jersey-media-json-jettison 模块 到 pom.xml : 


<dependency> 
<groupiId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-json-jettison</artifactId> 
<version>2.16</version> 

</dependency> 


如 果 没 有 使 用 Maven ， 确 保 所 有 依赖 库 ( 详 见 jersey-media-json-jettison) 在 classpath 中 . 


9.1.5.2. JSON Notations 符号 


JettisonConfig 允许 你 使 用 两 种 JSON 符号 ， 每 种 序列 化 ISON 的 方式 是 不 同 的 。 下 面 是 支 
持 符号 的 列表 : 


e JETTISON MAPPED (RUZ) 
e BADGERFISH 


在 处 理 更 复杂 的 XML 文档 ， 你 可 能 想 要 使 用 这 些 符号 。 即 当 你 在 JAXB bean 处 理 多 个 XML 名 
称 空 间 。 


独立 的 符号 及 其 进一步 的 配置 选项 如 下 所 述 。 而 不 是 解释 规则 映射 XML 结构 转换 为 JSON, 描 
述 的 符号 将 使 用 一 个 简单 的 例子 。 以 下 是 JAXB bean, 它 将 被 使 用 。 


Example 9.17. JAXB beans for JSON supported notations description, simple address bean 


QXmlRootElement 

public class Address { 
public String street; 
public String town; 


public Address(){} 
public Address(String street, String town) { 


this.street - street; 
this.town - town; 


Example 9.18. JAXB beans for JSON supported notations description, contact bean 


QXmlRootElement 
public class Contact { 


public int id; 

public String name; 

public List«Address» addresses; 

public Contact() {}; 

public Contact(int id, String name, List<Address> addresses) { 
this.name - name; 
this.id - id; 


this.addresses - 
(addresses != null) ? new LinkedList<Address>(addresses) : null; 


以 下 文本 主要 工作 是 contact bean 初始 化 : 


Example 9.19. JAXB beans for JSON supported notations description, initialization 


Address[] addresses = {new Address("Long Street 1", "Short Village")}; 
Contact contact = new Contact(2, "Bob", Arrays.asList(addresses) ); 


例子 中 contact bean 的 id=2, name="Bob" 包含 一 个 address (street="Long Street 1", 


town="Short Village"). 


下 面 所 有 的 配置 选项 描述 的 记录 也 在 JettisonConfig apix 


9.1.5.2.1. Jettison mapped notation 隐 射 符号 


如 果 你 需要 处 理 各 种 XML 名 称 空 间 , 你 会 发 现 Jettison 映射 符号 非常 有 用 。 人 允许 定义 一 个 特定 
名 称 空间 id 项 : 


@XmlElement (namespace="http://example.com") 
public int id; 


然后 你 只 需 配 置 从 XML 名 称 空间 映射 到 ISON 前 级 如 下 : 


Example 9.20. XML namespace to JSON mapping configuration for Jettison based mapped 
notation 


Map<String,String> ns2json = new HashMap<String, String>(); 

ns2json.put("http://example.com", "example"); 

context - new JettisonJaxbContext( 
JettisonConfig.mappedJettison().xml2JsonNs(ns2json).build(), 
types); 


JSON 的 结果 就 像 下 面 的 例子 . 


Example 9.21. JSON expression with XML namespaces mapped into JSON 


"contact": { 
"example.id":2, 
"name":"Bob", 
"addresses": { 
"street":"Long Street 1", 
"town":"Short Village" 


请 注意 ,该 id 项 变 成 了 example.id 基于 XML 名 称 空间 映射 的 id。 如 果 你 有 更 多 的 XML 名 称 空 
间 的 XML ,您 需要 为 所 有 这 些 配置 合适 的 映射 。 


Jersey 版 本 2.2 中 引入 另 一 个 可 配置 的 选项 与 序列 化 ISON 数组 与 Jettison 的 映射 的 符号 。 当 
序列 化 元 素 代 表单 项 列表 /数组 时 ,您 可 能 想 要 使 用 以 下 Jersey 配置 方法 来 显 式 地 名 称 元 素 将 
其 视 为 数组 不 管 实际 内 容 是 什么 。 


Example 9.22. JSON Array configuration for Jettison based mapped notation 


context = new JettisonJaxbContext( 
JettisonConfig.mappedJettison().serializeAsArray("name").build(), 
types); 


JSON 结果 想 下 面 例子 ， 不 重要 的 行 已 经 删除 


Example 9.23. JSON expression with JSON arrays explicitly configured via Jersey 


"contact": { 


"name": ["Bob"], 


9.1.5.2.2. Badgerfish notation 
从 JSON 和 JavaScript 的 角度 来 看 ,这 种 表示 法 绝对 是 最 可 读 的 。 您 可 能 不 希望 使 用 它 ,除非 
你 需要 确保 你 的 JAXB bean 可 以 完美 地 读 写 和 JSON ,无 需 顾 及 任何 格式 配置 中 ,名 称 空间 


KE 


AF o 
JettisonConfig 使 用 badgerfish 符号 可 以 通过 下 面 语句 创建 
JettisonConfig.badgerFish().build() 


JSON 输出 如 下 : 


Example 9.24. JSON expression produced using badgerfish notation 


t 
"contact": { 
Mato MSE 
MES A 
u 
"name": { 
"$": "Bob" 
u 
"addresses": { 
"street": { 
"$":"Long Street 1" 
} 
"town": { 
"$": "Short Village" 
} 
} 
} 
} 


9.1.5.3. Configure and register 配置 和 注册 


若 使 用 Jettison 为 你 的 JSON (JAXB/POJO) 提供 者 ， 需 给 JAXBContext (如 果 需 要 ) 注册 
JettisonFeature 和 ContextResolver 到 在 你 的 配置 (client/server). 


Example 9.25. ContextResolver 


@Provider 
public class JaxbContextResolver implements ContextResolver«JAXBContext» { 


private final JAXBContext context; 

private final Set<Class<?>> types; 

private final Class<?>[] cTypes = {Flights.class, FlightType.class, AircraftType.c 
lass); 


public JaxbContextResolver() throws Exception { 
this.types = new HashSet<Class<?>>(Arrays.asList(cTypes) ); 
this.context = new JettisonJaxbContext(JettisonConfig.DEFAULT, cTypes); 


@Override 
public JAXBContext getContext(Class<?> objectType) { 
return (types.contains(objectType)) ? context : null; 


Example 9.26. Building client with Jettison JSON feature enabled. 


final Client client = ClientBuilder.newBuilder() 

.register(JaxbContextResolver.class) // No need to register this provider if 
no special configuration is required. 

.register(JettisonFeature.class) 

.build(); 


Example 9.27. Creating JAX-RS application with Jettison JSON feature enabled. 


// Create JAX-RS application. 

final Application application - new ResourceConfig() 
.packages("org.glassfish.jersey.examples.jettison") 
.register(JaxbContextResolver.class) // No need to register this provider if 

no special configuration is required. 
.register(JettisonFeature.class); 


9.1.5.4. Examples 例子 


Jersey 提供 JSON Jettison 的 例子 . 


8.1.6. @JSONP - JSON with Padding Support 


Jersey 提供 开 箱 即 用 的 支持 JSONP - JSON with Padding。 以 下 条 件 必须 满足 利用 此 功能 : 


e 资源 的 方法 , 它 应 该 返回 JSON, 包 装 需 要 由 @JSONP 注释 的 。 
e MessageBodyWriter application/json 媒体 类 型 ,也 接受 资源 方法 的 返回 类 型 ,需要 注册 ( 见 


本 章 JSON 部 分 ) * 
e 用 户 的 请 求 必须 包含 Accept 标 头 的 JavaScript 定义 媒体 类 型 ( 见 下 文 )。 


可 接受 的 媒体 类 型 兼容 @JSONP 是 :pplication/javascript, application/x-javascript, 
application/ecmascript, text/javascript, text/x-javascript, text/ecmascript, text/jscript. 


Example 9.28. Simplest case of using @JSONP 


@GET 
@JSONP 
@Produces({"application/json", "application/javascript"}) 
public JaxbBean getSimpleJSONP() { 
return new JaxbBean("jsonp"); 


} 


假设 我 们 有 注册 一 个 JSON 提供 者 和 JaxbBean 看 起 来 像 : 


Example 9.29. JaxbBean for @JSONP example 


QXmlRootElement 
public class JaxbBean { 


private String value; 
public JaxbBean() {} 


public JaxbBean(final String value) { 
this.value - value; 


} 


public String getValue() { 
return value; 


} 


public void setValue(final String value) { 
this.value = value; 


} 


当 你 发 送 一 个 GET 请 求 接受 标题 设置 为 application/javascript 你 会 得 到 一 个 结果 实体 看 起 来 
像 : 


callback({ 
"value" : "jsonp", 


}) 


当然 ,方法 配置 包装 方法 返回 的 实体 默认 回调 可 以 看 到 在 前 面 的 例子 。@JSONP 有 两 个 参数 ， 
可 以 配置 :回调 ,queryParam。 回 调 的 名 称 代 表 JavaScript 应 用 程序 定义 的 回调 函数 。 
queryParam, 第 二 个 参数 定义 的 名 称 查询 参数 的 回调 函数 的 名 称 使 用 在 请 求 (如 果 存 在 )。 
queryParam 值 默认 为 _ callback, 所 以 即使 你 不 自己 设置 查询 参数 的 名 称 ,客户 总 是 可 以 影响 
结果 包装 JavaScript 回调 方法 的 名 称 。 


queryParam 值 (如 果 设 置 ) 总 是 优先 于 回调 函数 值 。 
稍微 改 下 代码 


Example 9.30. Example of @JSONP with configured parameters. 


@GET 
@Produces({"application/json", "application/javascript"}) 
@JSONP(callback = "eval", queryParam = "jsonpCallback") 
public JaxbBean getSimpleJSONP() { 
return new JaxbBean("jsonp"); 
} 
两 次 提交 : 
curl -X GET http://localhost:8080/jsonp 
将 返回 
eval({ 
"value" : "jsonp", 
3) 
以 及 
curl -X GET http://localhost:8080/jsonp?jsonpCallback=alert 
将 返回 
alert({ 


"value" : "jsonp", 


}) 


Example. 这 里 提供 示例 . 


9.2. XML 


正如 您 可 能 已 经 知道 ,Jersey 使 用 MessageBodyWriter 7» MessageBodyReader 年 代 来 解析 传 
入 的 请 求 和 创建 传 出 的 响应 。 每 个 用 户 都 可 以 创建 自己 的 表现 但 是 ... 这 是 不 建议 这 样 做 。 
XML 是 证 明 交 换 信息 的 标准 ,特别 是 在 web 服务 。Jersey 支持 低 水 平 数据 类 型 用 于 直接 操作 和 
JAXB XML 实体 。 


9.2.1. Low level XML support 低级 XML 支持 


Jersey 目前 支持 一 些 低 水 平 的 数据 类 型 :StreamSource, SAXSource, DOMSource 和 
Document。 您 可 以 使 用 这 些 类 型 的 返回 类 型 或 方法 (资源 ) 参 数 。 让 说 我 们 想 要 测试 这 个 功能 ， 
RMA helloworld 示 例 作为 起 点 。 所 有 我 们 需要 做 的 就 是 添加 方法 (资源 ) 的 消耗 和 产生 的 
XML 和 类 型 将 使 用 上 面 提 到 的 。 


Example 8.31. Low level XML test - methods added to HelloWorldResource.java 


@POST 

@Path("StreamSource" ) 

public StreamSource getStreamSource(StreamSource streamSource) { 
return streamSource; 


} 


@POST 

@Path("SAXSource") 

public SAXSource getSAXSource(SAXSource saxSource) { 
return saxSource; 


} 


@POST 

@Path("DOMSource" ) 

public DOMSource getDOMSource(DOMSource domSource) { 
return domSource; 


} 


@POST 

@Path("Document") 

public Document getDocument(Document document) { 
return document; 


} 


MessageBodyWriter 和 MessageBodyReader 都 在 这 个 例子 中 使 用 了 ,我 们 需要 的 是 一 个 
POST 请 求 XML 文档 作为 一 个 请 求 的 实体 。 让 这 只 尽 可 能 简单 的 根 元 素 没 有 内 容 将 发 送 :”。 
您 可 以 创建 JAX-RS 客户 端 , 或 使 用 其 他 一 些 工 具 , 例 如 curl: 


curl -v http://localhost:8080/base/helloworld/StreamSource -d "" 


你 应 该 从 我 们 的 服务 得 到 完全 相同 的 XML ;在 本 例 中 ,XML 头 添 加 到 响应 但 内 容 停 留 。 自 由 的 
遍历 所 有 资源 。 


9.2.2. Getting started with JAXB 开始 


好 的 开始 ,人 们 已 经 有 了 一 些 JAXB 注解 的 经 验 ,例子 是 是 JAXB 示 例 。 你 可 以 看 到 不 同 的 用 

例 。 本 文 主要 是 针对 那些 没有 JAXB 经 验 。 别 指望 所 有 可 能 的 注释 和 他 们 的 组 合 将 在 这 一 

章 ,JAXB(JSR 222 实 现 ) 是 相当 复杂 和 全 面 。 但 如 果 你 只 是 想 知 道 如 何 与 REST 服务 交换 XML 
消息 ,你 看 着 合适 的 章节 。 


可 以 从 简单 的 例子 开始 。 让 我 们 说 我 们 有 类 Planet 和 服务 生产 的 “Planets”。 


Example 9.32. Planet class 


QXmlRootElement 

public class Planet { 
public int id; 
public String name; 
public double radius; 


Example 9.33. Resource class 


QPath("planet") 
public class Resource { 


QGET 
QProduces(MediaType.APPLICATION XML) 
public Planet getPlanet() { 

final Planet planet - new Planet(); 


planet.id - 1; 
planet.name - "Earth"; 
planet.radius - 1.0; 


return planet; 


你 可 以 看 到 有 一 些 额外 的 注释 声明 类 Planet, LH X ()XmlRootElement » 3t € — 4- JAXB 注 
释 的 java 类 映射 到 XML 元 素 。 我 们 不 需要 指定 任何 其 他 ,因为 Planet 非常 简单 的 类 ,所 有 的 字 
段 都 是 公开 的 。 在 这 种 情况 下 ,XML 元 素 名 称 将 派生 类 名 或 你 可 以 设置 名 称 属 

性 :@XmlRootElement(name="yourName")。 


我 们 的 资源 类 将 响应 GET/planet 请 求 


<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<planet> 

<id>1</id> 

<name>Ear th</name> 

<radius>1.0</radius> 
</planet> 


这 可 能 正 是 我 们 想 要 的 .…… 与 否 。 或 者 我 们 可 能 不 关心 ,因为 我 们 可 以 使 用 JAX-RS 客户 端 发 
出 请 求 该 资源 ,这 很 容易 : 
Planet planet = webTarget.path("planet").request(MediaType.APPLICATION XML TYPE).get(P 


lanet.class); 


有 预先 创建 WebTarget 对 象 指向 我 们 的 应 用 程序 的 上 下 文 根 , 只 需 添加 路 径 (在 我 们 的 例子 中 
是 planet), 接 收 header( 不 是 强制 性 的 ,但 服务 可 以 提供 不 同 的 内 容 基 于 这 头 ,例如 可 以 为 
text/html 在 web 浏览 器 ), 最 后 我 们 指定 ,我 们 预计 Planet 类 通过 GET 请 求 。 
不 仅 可 能 需要 生成 XML ,我 们 可 能 希望 使 用 它 。 
Example 9.34. Method for consuming Planet 

@POST 

@Consumes (MediaType .APPLICATION_XML) 


public void setPlanet(Planet planet) { 
System.out.println("setPlanet " + planet); 


} 


有 效 的 请 求 后 ,服务 将 打印 字符 串 表示 的 Planet, 可 以 像 Planet{id=2, name='Mars', 
radius=1.51}。 通 过 JAX-RS 客户 端 你 能 做 到 : 


webTarget.path("planet").post(planet); 


o 


如 果 有 需要 其 他 ( 非 默认 的 ) XML 表示 ,其 他 JAXB 注解 需要 被 使 用 。 简 化 这 一 过 程 通常 是 由 从 
XML 模式 生成 java 源 代码 是 通过 XML 到 java 编译 器 和 它 的 xjc 是 JAXB 的 一 部 分 


9.2.3. POJOs 


有 时 ， 你 不 能 或 者 不 想 在 代码 里 面 使 用 注解 ， 但 又 想 用 消费 和 生成 XML 的 类 的 表现 形式 。 这 
种 情况 下 就 可 以 用 JAXBElement 。 下 面 例 子 就 是 没有 用 @XmlRootElement 注解 : 


Example 9.35. Resource class - JAXBElement 


@Path("planet") 
public class Resource { 


@GET 

QProduces(MediaType.APPLICATION XML) 

public JAXBElement«Planet» getPlanet() { 
Planet planet - new Planet(); 


planet.id - 1; 
planet.name - "Earth"; 
planet.radius - 1.0; 


return new JAXBElement<Planet>(new QName("planet"), Planet.class, planet); 


@POST 

QConsumes (MediaType.APPLICATION XML) 

public void setPlanet(JAXBElement«Planet» planet) { 
System.out.println("setPlanet " + planet.getValue()); 


正如 您 可 以 看 到 的 ,一 切 都 是 用 了 JAXBElement 就 会 复杂 一 些 。 这 是 因为 现在 需要 显 式 地 设 
置 元 素 名 称 的 给 Planet 类 的 XML 表示。 客户 端 比 服 务 器 端 更 加 复杂 ,因为 你 不 能 做 
JAXBElement<Planet> 所 以 JAX-RS 客户 端 API 提供 了 如 何 通过 声明 GenericType<T> 的 子 


类 解决 它 
Example 9.36. Client side - JAXBElement 


// GET 
GenericType<JAXBElement<Planet>> planetType = new GenericType<JAXBElement<Planet>>() { 


}; 


Planet planet = (Planet) webTarget.path("planet").request(MediaType.APPLICATION XML TY 
PE).get(planetType).getValue(); 
System.out.println("Z££ " + planet); 


// POST 
planet - new Planet(); 


HUE can 


webTarget.path("planet").post(new JAXBElement<Planet>(new QName("planet"), Planet.clas 
s, planet)); 


9.2.4. Using custom JAXBContext 使 用 自 定 义 
JAXBContext 


有 些 场景 适合 使 用 自 定 义 JAXBContext。JAXBContext 的 创建 是 一 个 昂贵 的 操作 ， 如 果 你 已 
经 创建 了 一 个 ， 相 同 的 实例 被 Jersey 使 用 。 其 他 可 能 使 用 的 情况 是 当 你 需要 给 JAXBContext 
建立 一 些 特 定 的 东西 ， 例 如 设置 不 同 的 类 装载 器 。 


Example 9.37. PlanetJAXBContextProvider 


@Provider 
public class PlanetJAXBContextProvider implements ContextResolver<JAXBContext> { 
private JAXBContext context = null; 


public JAXBContext getContext(Class<?> type) { 
if (type != Planet.class) { 
return null; // we don't support nothing else than Planet 


} 


if (context == null) { 
try { 
context = JAXBContext.newInstance(Planet.class); 
} catch (JAXBException e) { 
// log warning/error; null will be returned which indicates that this 
// provider won't/can't be used. 


j 


return context; 


上 面 示例 简单 创建 JAXBContext 的 过 程 , 所 有 你 ee @Provider 注释 放 上 ， 
这 样 Jersey 就 能 找到 它 。 用 户 有 时 在 客户 端 使 用 provider. (提供 者 ) 类 出 问题 ,所 以 只 是 为 
了 提醒 一 一 你 必须 在 客户 端 配置 (客户 端 做 任何 事情 不 像 通过 服务 器 包 扫 描 ) 声 明 他 们 。 


Example 9.38. Using Provider with JAX-RS client 


ClientConfig config = new ClientConfig(); 
config.register (Planet JAXBContextProvider.class); 


Client client = ClientBuilder.newClient(config); 


9.2.5. MOXy 


如 果 你 想 使 用 MOXy 作为 JAXB 实现 而 不 是 JAXB RI 您 有 两 种 选择 。 您 可 以 使 用 标准 的 
JAXB 机 制 来 定义 从 JAXBContext 实例 将 获得 (有 关 此 主题 的 更 多 信息 , 读 JavaDoc 
JAXBContext) 的 JAXBContextFactory 或 者 你 可 以 将 jersey-media-moxy 模块 添加 到 您 的 项 
目 和 注册 /配置 MoxyXmlFeature 类 /实例 的 Configurable。 


Example 9.39. Add jersey-media-moxy dependency. 


<dependency> 
<groupiId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-moxy</artifactId> 
<version>2.16</version> 

</dependency> 


Example 9.40. Register the MoxyXmlFeature class. 


final ResourceConfig config = new ResourceConfig( ) 
.packages("org.glassfish.jersey.examples.xmlmoxy") 
.register(MoxyXmlFeature.class); 


Example 9.41. Configure and register an MoxyXmlFeature instance. 


// Configure Properties. 
final Map<String, Object» properties = new HashMap<String, Object>(); 
WE aua 


// Obtain a ClassLoader you want to use. 
final ClassLoader classLoader - Thread.currentThread().getContextClassLoader(); 


final ResourceConfig config - new ResourceConfig() 
.packages("org.glassfish.jersey.examples.xmlmoxy") 
.register(new MoxyXmlFeature( 
properties, 
classLoader, 
true, // Flag to determine whether eclipselink-oxm.xml file should be used for 
lookup. 
CustomClassA.class, CustomClassB.class // Classes to be bound. 


)); 


9.3. Multipart 


9.3.1. Overview 概述 


在 JAX-RS 运行 环境 ,这 个 模块 中 的 类 提供 了 multipart/* 请 求 和 响应 体 的 集成 。 注 册 提供 者 的 
集合 是 为 杠杆 ， 在 这 样 的 一 个 消息 体 部 分 的 内 容 类 型 重用 同一 
MessageBodyReader/MessageBodyWriter 实现 将 用 于 该 内 容 类 型 作为 一 个 独立 的 实体 。 


下 面 列 出 的 是 目前 支持 常见 的 MIME MultiPart : 


e MIME-Version : 1.0 HTTP header 包含 在 生成 的 响应 中 。 这 是 可 以 接受 的 ， 但 在 处 理 请 
求 中 不 是 必需 的 。 

e MessageBodyReader 实现 ， 用 于 消耗 MIME MultiPart 实体 。 

e MessageBodywriter<T> 实现 用 于 产生 MIME MultiPart 实体 。 适 当 的 @provider 是 基于 
媒体 类 型 ， 用 于 序列 化 响应 体 的 每 个 部 分 。 

e 如 果 不 是 已 经 存在 ， 在 平常 的 Content-Type header 创建 一 个 可 选 的 适当 的 边界 参数 。 


更 多 信息 ， 见 Multi Part 


9.3.1.1. Dependency 依赖 
添加 jersey-media-multipart 到 pom.xml 


<dependency> 
<groupiId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-multipart</artifactId> 
<version>2.16</version> 

</dependency> 


如 果 你 不 使 用 Maven, 确 保有 所 有 需要 的 依赖 〈 见 jersey-media-multipart) 在 类 路 径 


9.3.1.2. Registration 注册 
为 了 在 客户 端 /服务 端 代 码 使 用 jersey-media-multipart 模块 的 功能 ， 先 注册 MultiPartFeature 


Example 9.42. Building client with MultiPart feature enabled. 


final Client client = ClientBuilder .newBuilder( ) 
.register(MultiPartFeature.class) 
.build(); 


Example 9.43. Creating JAX-RS application with MultiPart feature enabled. 


// Create JAX-RS application. 

final Application application = new ResourceConfig() 
.packages("org.glassfish.jersey.examples.multipart") 
.register(MultiPartFeature.class) 


9.3.1.3. Examples 实例 


见 Multipart Web Application Example 


9.3.2. Client 客户 端 


MultiPart 类 (RFA) 可 以 当做 实体 指向 使 用 jersey-media-multipart 的 模块 在 客户 端 。 这 个 
X 表现 为 MIME multipart 消息 并 且 能 够 容纳 任意 数量 的 BodyPart。 MultiPart 实体 默认 的 媒 
体 类 型 multipart/mixed > 而 BodyPart 是 text/plain ° 


Example 9.44. MultiPart entity 


final MultiPart multiPartEntity = new MultiPart() 
.bodyPart(new BodyPart().entity("hello")) 
.bodyPart(new BodyPart(new JaxbBean("xml"), MediaType.APPLICATION XML TYPE)) 
.bodyPart(new BodyPart(new JaxbBean("json"), MediaType.APPLICATION JSON TYPE)) 


, 


final WebTarget target = // Create WebTarget. 
final Response response - target 
.request() 
.post(Entity.entity(multiPartEntity, multiPartEntity.getMediaType())); 


如 果 发 送 multiPartEntity 到 服务 端 ， 实 体 的 Content-Type header 在 HTTP message 就 像 下 
面 那样 : ( 别 忘 了 注册 JSON 提供 者 ) 


Example 9.45. MultiPart entity in HTTP message. 


Content-Type: multipart/mixed; boundary=Boundary_1_829077776_1369128119878 


--Boundary 1 829077776 1369128119878 
Content-Type: text/plain 


hello 
--Boundary 1 829077776 1369128119878 
Content-Type: application/xml 


<?xml version="1.0" encoding="UTF-8" standalone="yes"?><jaxbBean><value>xml</value></j 
axbBean> 

--Boundary 1 829077776 1369128119878 

Content-Type: application/json 


{"value":"json"} 
--Boundary 1 829077776 1369128119878-- 


当 涉 及 到 form 表单 时 ， (例如 媒体 类 型 multipart/form-data) 且 有 多 个 字段 ， 有 一 个 更 方便 
使 用 的 类 - FormDataMultiPart。 它 会 自动 设置 为 FormDataMultiPart 实体 的 媒体 类 型 为 
multipart/form-data 及 Content-Disposition 报头 为 FormDataBodyPart 。 


Example 9.46. FormDataMultiPart entity 


final FormDataMultiPart multipart = new FormDataMultiPart() 
.field("hello", "hello") 
.field("xml", new JaxbBean("xml")) 
.field("json", new JaxbBean("json"), MediaType.APPLICATION JSON TYPE); 


final WebTarget target = // Create WebTarget. 


final Response response - target.request().post(Entity.entity(multipart, multipart.get 
MediaType())); 


为 了 说 明 使 用 FormDataMultiPart 替换 FormDataBodyPart 不 同 点 ， 可 以 看 下 
FormDataMultiPart 的 HTML 消息 中 的 实体 : 


Example 9.47. FormDataMultiPart entity in HTTP message. 


Content-Type: multipart/form-data; boundary-Boundary 1 511262261 1369143433608 


--Boundary 1 511262261 1369143433608 
Content-Type: text/plain 
Content-Disposition: form-data; name="hello" 


hello 

--Boundary 1 511262261 1369143433608 
Content-Type: application/xml 
Content-Disposition: form-data; name-z'xml" 


<?xml version="1.0" encoding-"UTF-8" standalone="yes"?><jaxbBean><value>xml</value></j 
axbBean> 

--Boundary 1 511262261 1369143433608 

Content-Type: application/json 

Content-Disposition: form-data; name="json" 


{"value":"json"} 
--Boundary 1 511262261 _ 1369143433608 - - 


对 于 许多 用 户 来 说 常见 的 情况 是 从 客户 端 向 服务 器 发 送 文件 。 为 了 这 个 目的 ， 你 可 以 使 用 来 
自 org.glassfish.jersey.jersey.media.multipart 包 类 ， 如 FileDataBodyPart 或 
StreamDataBodyPart 


Example 9.48. Multipart - sending files. 


// MediaType of the body part will be derived from the file. 
final FileDataBodyPart filePart = new FileDataBodyPart("my pom", new File("pom.xml")); 


final FormDataMultiPart multipart - new FormDataMultiPart() 
.field("foo", "bar") 
.bodyPart(filePart); 


final WebTarget target - // Create WebTarget. 


final Response response - target.request() 
.post(Entity.entity(multipart, multipart.getMediaType())); 


不 要 使 用 ApacheConnectorProvider ` GrizzlyConnectorProvider 或 者 
JettyConnectorProvider 连接 器 实现 Jersey Multipart features ° JL, Header modification issue 


9.3.3. Server 


从 服务 器 返回 一 个 multipart 响应 到 客户 端 ， 跟 客户 端 描述 的 美誉 太 大 不 同 。 为 获得 客户 端 
发 送 的 多 个 实体 的 应 用 中 ， 你 可 以 使 用 两 种 方法 : 


e 注入 整个 MultiPart 实体 
e 通过 @FormDataParam 注解 ,将 请 求 中 特定 form-data multipar 部 分 注入 。 


9.3.3.1. Injecting and returning the MultiPart entity 
注入 和 返回 MultiPart 实体 


MultiPart 类 型 的 工作 方式 与 注入 /返回 其 他 实体 类 型 不 同 。Jersey 提供 
MessageBodyReader«T» 用 来 读 取 请 求实 体 ， 并 且 注 入 这 个 实体 到 资源 方法 的 参数 中 ， 而 
MessageBodywriter<T> 用 于 实体 的 输出 。 你 可 以 预计 ,多 部 分 或 FormDataMultiPart( 多 部 分 / 格 
式 数据 媒体 类 型 ) 对 象 注入 资源 的 方法 。 你 可 以 预期 MultiPart 或 FormDataMultiPart 
(multipart/form-data 媒体 类 型 ) 对 象 用 来 注入 到 资源 方法 中 。 


Example 9.49. Resource method using MultiPart as input parameter / return value. 


@POST 

@Produces("multipart/mixed" ) 

public MultiPart post(final FormDataMultiPart multiPart) { 
return multiPart; 


} 


9.3.3.2. Injecting with @FormDataParam 通过 
@FormDataParam 注入 


如 果 你 只 是 需要 multipart/form-data 请 求实 体 到 资源 的 方法 中 ， 可 以 使 用 
@FormDataParam 注解 。 


这 个 注解 结合 使 用 的 媒体 类 型 multipart/form-data 应 该 包含 文件 、 非 ASCII 数据 , 和 编译 数据 
的 提交 和 消费 形式 。 


注解 的 类 型 参数 可 以 是 下 列 之 一 (更 多 详细 描述 见 javadoc @FormDataParam): 


e FormDataBodyPart - 参数 的 值 将 会 是 第 一 个 命名 的 body 部 分 或 null 如 果 这 样 的 body 
部 分 不 存在 

e FormDataBodyPart 的 集合 -参数 的 值 将 会 是 一 个 或 多 个 具有 相同 名 称 的 命名 的 body 部 位 
或 null 如 果 这 样 的 body 部 位 不 存在 。 

e FormDataContentDisposition - 参数 的 值 将 被 会 是 第 一 个 命名 的 body 部 分 的 内 容 处 理 部 
分 或 null 如 果 这 样 的 body 部 分 不 存在 。 

。 FormDataContentDisposition 集合 。 参 数 的 值 将 一 个 或 多 个 内 容 处 理 指定 的 body 部 分 使 
用 相同 的 名 称 或 null 如 果 这 样 命名 的 body 部 分 是 不 存在 的 。 

e 一 种 类 型 的 消息 体 的 读者 可 以 给 出 第 一 个 命名 为 主体 的 媒体 类 型 。 参 数 的 值 将 使 用 给 定 
类 型 的 消息 体 读者 阅读 的 结果 ， 对 指定 的 媒体 类 型 ， 以 及 指定 的 body 的 一 部 分 作为 输入 
字 节 。 


果 没 有 指定 部 分 存在 ,有 一 个 默认 值 存在 用 @DefaultValue 声明 ， 那 么 媒体 类 型 将 被 设置 为 
text/plain 。 参 数 的 值 将 被 阅读 的 结果 使 用 消息 体 的 读者 类 型 二 媒体 类 型 text/plain,UTF-8 编 
码 的 字 节 的 默认 值 作 为 输入 。 


果 没 有 消 息 体 读者 可 用 ， 那么 类 型 T 符合 类 类 型 @FormParam RE 通过 @FormParam 特定 处 理 ， 
pore d 节 的 字符 串 实 例 指 定 的 body 部 分 使 用 字符 串 类 型 的 消息 体 的 读者 
和 媒体 类 型 的 text/plain。 


果 没 有 指定 部 分 表现 那么 处 理 执行 规定 的 @FormParam . 


Example 9.50. Use of @FormDataParam annotation 


@POST 
@Consumes (MediaType.MULTIPART FORM DATA TYPE) 
public String postForm( 
@DefaultValue("true") QFormDataParam("enabled") boolean enabled, 
@FormDataParam("data") FileData bean, 
@FormDataParam("file") InputStream file, 
@FormDataParam("file") FormDataContentDisposition fileDisposition) { 


VL uos 


示例 中 ， 服 务 器 消耗 multipart/form-data 请 求实 体 body ,包含 了 一 个 可 选 的 指定 的 body 部 
分 ， 和 两 个 必须 的 指定 的 body 部 分 数据 和 文件 。 


可 选 部 分 启动 是 当做 一 个 布尔 值 处 理 ， 如 果 这 部 分 不 再 那么 值 是 true。 
数据 部 分 当做 JAXB bean 处 理 ， 包 含 了 下 面部 分 的 元 数据 。 


文件 部 分 是 上 次 的 文件 ， 处 理 成 InputStream。 从 Content-Disposition header 看 到 附加 信息 
关于 文件 可 以 通过 参数 fileDisposition 访问 。 


提示 


@FormDataParam 注解 同样 适用 于 字段 
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Chapter 11. Asynchronous Services and 
Clients 异步 服务 器 和 客户 端 


Chapter 20. MVC Templates 模板 


Jersey 提供 了 支持 Model-View-Controller (MVC) 设计 模式 的 扩展 。 

在 Jersey 组 件 的 上 下 文中 ， 在 MVC 模式 中 的 Controller 对 应 于 一 个 资源 类 或 方法 ，View 对 
应 绑 定 到 资源 类 或 方法 的 模板 ，Model 对 应 从 资源 方法 (Controller) 返回 的 Java 对 象 (或 
Java Bean) 。 

注 : 从 本 章 的 一 些 段 落 /例子 来 自 Paul Sandoz 的 MVCJ 博客 。 


在 Jersey 2， 基 础 MVC API 由 两 个 类 组 成 (在 org.glassfish.jersey.server.mvc 包 ) ， 可 用 于 
绑 定 模型 到 视图 (模板) ， 分 别 是 Viewable 和 @Template。 在 使 用 Jersey MVC 模板 支持 
时 ， 这 些 类 确定 了 采用 显示 还 是 隐士 式 的 处 理 方法 。 


20.1. Viewable 


为 了 让 资源 的 方法 显 式 地 返回 对 于 一 个 视图 模板 和 数据 模型 被 使 用 的 引用 。 为 此 ，Jersey 1 
引入 了 Viewable 类 ， 目 前 也 存在 于 〈 不 同 的 包 下 ) Jersey 2。 见 下 面 一 个 简单 的 例子 ， 
Example 20.1, “Using Viewable in a resource class” 


Example 20.1. Using Viewable in a resource class 


package com.example; 


QPath("foo") 
public class Foo { 


@GET 
public Viewable get() { 
return new Viewable("index.foo", "FOO"); 


} 


top kk 


在 这 个 例子 中 ，foo JAX-RS 资源 类 是 控制 器 ，Viewable 实例 提供 的 数据 模型 (FOO 字符 
串 ) 和 引用 装载 进 与 之 关联 的 视图 模板 (index.foo) 里 。 

提示 : 所 有 的 HTTP 方法 都 可 以 返回 Viewable 实例 。 因 此 ，POST 方法 可 能 会 返回 一 个 模 
板 引 用 的 模板 ， 产 生 一 个 HTML Form 表单 的 视图 


20.2. @Template 


20.2.1. Annotating Resource methods 注释 资源 的 方法 


不 需要 每 次 都 用 Viewable ， 如 果 你 想 绑 定 模型 到 模板 上 。 为 了 让 资源 方法 可 读 性 更 强 (AT 
避免 宛 长 的 包装 模板 参考 模型 到 Viewable) ,你 可 以 简单 的 通过 (Template 注释 资源 的 方 

法 。 从 前 面 的 例子 ， 我 们 做 下 修改 ， 见 Example 20.2, “Using @Template on a resource 
method” 


Example 20.2. Using @Template on a resource method 


package com.example; 


QPath("foo") 
public class Foo { 


QGET 

QTemplate("index.foo") 

public String get() { 
return "FOO"; 


} 


在 这 个 例子 中 ，Foo JAX-RS 资源 类 仍然 是 上 一 节 中 的 控制 器 ， 但 是 模型 现在 是 返回 注解 资 
源 的 方法 。 


这 种 方法 的 处 理 基 本 上 是 和 放 回 一 个 Viewable 类 实例 是 相同 的 。 如 果 一 个 方法 
QTemplate 注解 的 ， 也 可 返回 Viewable 类 实例 ，Viewable 类 实例 将 优先 于 那些 在 注释 的 定 
产生 的 媒体 类 型 ， 是 Viewable 还 是 @Template 将 有 方法 或 者 类 级 别 的 @produces 注解 决 


moe e di 


20.2.2. Annotating Resource classes 注解 资源 类 


资源 类 可 以 隐 式 地 通过 gremplate 注解 来 与 模板 进行 关联 。 见 Example 20.3, "Using 
@Template on a resource class” 


Example 20.3. Using @Template on a resource class 


@Path("foo") 
@Template 
public class Foo { 


public String getFoo() { 
return "FOO"; 


} 


这 个 例子 需要 更 多 的 解释 是 这 样 的 。 首 先 ， 你 可 能 已 经 注意 到 ， 没 有 定义 资源 的 方法 为 JAX- 
RS 资源 。 同 时 ， 没 有 被 定义 的 模板 引用 。 在 这 种 情况 下 ， 由 于 @Template 注释 放 在 资源 类 中 
不 包含 任何 信息 ， 默 认 模 板 将 使 用 相对 引用 index ( 详 见 20.3 节 ，20.3. Absolute vs. Relative 
template reference) 。 对 于 缺少 资源 的 方法 ， 上 默认 的 @6ET 方法 将 自动 生成 的 Foo 资源 ( 现 
在 是 MVC 的 控制 器 ) 。 生 成 的 资源 的 方法 执行 与 下 列 显示 资源 的 方法 的 实现 是 等 效 的 : 


@GET 
public Viewable get() { 
return new Viewable("index", this); 


} 


可 见 ， 资 源 类 充当 了 model 的 角色 。 产 生 媒 体 类 型 是 由 声明 在 资源 类 的 @produces 注解 决定 
的 ， 如 果 需 要 的 话 。 


ER: 在 这 种 基于 资源 类 的 隐 式 的 MVC 视图 模板 中 ， 控 制 器 同时 也 是 模型 。 在 这 种 情况 下 ， 
模板 引用 index 是 特殊 的 ， 它 的 模板 引用 关联 的 是 控制 器 实例 本 身 。 


下 面 例子 ，MVC 控制 器 以 JAX-RS @GET 子 资 源 方法 来 表示 ， 同 时 也 可 以 在 资源 类 中 注 明 
@Template 来 生成 


@GET 

@Path("{implicit-view-path-parameter}") 

public Viewable get(@PathParameter("{implicit-view-path-parameter}") String template) 
{ 


return new Viewable(template, this); 


} 


这 允许 Jersey 来 支持 隐 式 的 子 资源 模板 。 举 例 ， 一 个 在 foo/bar 路 径 的 JAX-RS 将 视图 使 用 
相对 模板 引用 bar ,分 解 为 绝对 模板 引用 /com/foo/Foo/bar 


换 名 话说， 一 个 HTTP GET 请 求 /foo/bar 会 通过 Foo 资源 方法 自动 处 理 产 生 并 将 请 求 转 到 
注册 模板 处 理 器 来 支持 绝对 参考 引用 /com/foo/Foo/bar， 其 中 模型 仍然 是 相同 的 JAX-RS 资 
源 类 Foo 的 一 个 实例 。 


20.2. 模板 
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20.3. 绝对 vs. 相对 模块 引用 


如 在 上 一 节 讨 论 @Template 和 Viewable 可 提供 的 方式 来 定义 一 个 参考 模板 。 现 在 我 们 将 讨 
论 如 何 将 这 些 值 解释 和 如 何 发 现 具 体 的 模板 。 


20.3.1. 相对 模块 引用 


相对 引用 是 指 任何 路 径 不 以 1 字符 开头 (如 index.foo)。 这 种 类 型 的 引用 ， 将 会 通过 前 面 加 上 
最 后 匹配 的 完全 名 字 的 值 来 转 为 绝对 路 径 。 


考虑 Example 20.3, “Using @Template on a resource class”, 模 板 名 称 引 用 index 是 一 个 相对 
值 ， Uy 将 会 使 用 完全 匹配 的 类 名 称 Foo 来 转 为 绝对 模板 引用 (更 多 详 见 Viewable) ， 我 
们 的 例子 


"Icom/foo/Foo/index" 


Jersey 将 会 搜索 所 有 的 注册 的 模板 处 理 器 ( 见 20.7. Writing Custom Templating Engines) 来 
找到 可 以 转 为 绝对 模板 引用 的 模板 处 理 器 。 如 果 这 样 的 模板 处 理 器 找到 了 ， 那 么 可 以 被 “处 
理 ” 的 模板 将 会 使 用 提供 的 数据 模型 来 处 理 。 


注意 : 如 果 不 提供 或 空 的 模板 参考 【无 论 是 在 Viewable 或 通过 @Template) 那么 假设 为 
index 引用 ， 对 这 个 值 的 所 有 进一步 的 处 理 是 这 一 价值 。 


20.3.2. 绝对 模板 引用 
修改 我 们 的 Foo 资源 
Example 20.4. Using absolute path to template in Viewable 


@GET 
public Viewable get() 1 
return new Viewable("/index", "F00"); 


} 


这 个 例子 ， 模 板 引 用 是 以 "开头 ， 所 以 无 需 进 行 绝 对 化 ， 就 已 经 是 绝对 引用 了 。 


绝对 模板 引用 以 "1" 字符 开头 ，( 如 /com/example/index.foo) ， 无 需 再 做 转换 ， 就 能 通过 提 
供 的 路 径 找 到 模板 。 


注意 ， 然 而 ， 对 于 自 定义 模板 引擎 的 模板 处 理 器 可 以 修改 (和 支持 ) 绝对 模板 引用 通过 在 前 
面 添加 ' 基 模板 路 径 ' (如果 定义 ) 而 后 添加 模板 后 级 (如 foo) 如 果 后 组 不 提供 在 引用 中 。 


例如 ， 假 设 我 们 想 用 Mustache 模板 给 我 们 的 页 面 ， 我 们 定义 了 ' 基 模板 路 径 ' 作 为 页 面 。 那 么 
绝对 模板 引用 /com/example/Foo/index 模板 处 理 器 将 会 将 引用 转换 成 以 下 路 
4% : /pages/com/example/Foo/index.mustache. 


20.4. MVC 错误 处 理 
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20.5. 注册 和 配置 
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20.6. 支持 的 模板 引擎 
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20.7. 写 自 定义 的 模板 引擎 
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20.8. 其 他 例子 
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Chapter 23. Spring DI 使 用 Spring 注入 


Jersey 提供 对 Spring DI 的 扩展 。 使 得 Jersey 在 使 用 Spring bean 时 就 像 是 JAX-RS 的 组 件 
(比如 资源 和 提供 者 ) 并 且 允 许 Spring 注入 Jersey 管理 的 组 件 中 。 


这 个 Spring 扩展 模块 配置 是 基于 注解 的 。 当 Spring bean 注入 ， 就 会 产生 的 受 Spring 管理 
的 JAX-RS 类 。 注入 的 Spring bean 不 只 是 通过 Spring XML 来 配置 ， 也 支持 用 Spring 的 
单 例 和 请 求 域 。 


为 了 JAX-RS 资源 能 和 Spring 的 功能 正常 工作 还 需要 代理 ， 比 如 Spring 的 事务 管理 (用 
@Transactional) > Spring Security 和 面向 切面 编程 (如 @Aspect)， 资 源 必 须 通过 Spring 的 
注解 @Component, @Service, @Controller 或 @Repository 来 管理 : 


import javax.ws.rs.GET; 
import javax.ws.rs.Path; 
import org.springframework.stereotype.Component; 


@Component 
QPath("/") 
public class SomeResource { 


QTransactional 

QGET 

public void updateResource() { 
HE 9 0 


} 


局 限 性 : Spring bean 不 能 通过 Spring XML 配置 被 直接 注射 到 JAX-RS 类 


23.1. Dependencies 依赖 


使 用 Jersey Spring Dl， 需要 添加 jersey-spring3 模块 


<dependency> 
<groupId>org.glassfish.jersey.ext</groupId> 
<artifactId>jersey-spring3</artifactId> 
<version>2.15</version> 

</dependency> 


上 述 模块 不 添加 任何 传递 依赖 于 Spring 的 模块 ， 所 以 你 将 需要 添加 Spring 3 依赖 , 请 添加 到 
依赖 列表 。 


23.2. Registration and Configuration ‘= # 
和 配置 


为 了 在 JAX-RS/Jersey 应 用 中 实现 Jersey Spring 3 DI 的 支持 ， 请 将 上 述 模块 添加 到 class- 
path 中 。 


23.3. Example 示例 


见 Spring DI Example 


